improve documentation
This commit is contained in:
Luca Filipozzi
parent
5468bb8e78
commit
22a445d2c4
1 changed files with 147 additions and 4 deletions
151
README.md
151
README.md
|
|
@ -16,7 +16,7 @@
|
||||||
|
|
||||||
# keycloak-regex-mapper
|
# keycloak-regex-mapper
|
||||||
|
|
||||||
This project provides a [keycloak][keycloak] broker mapper that maps a
|
This project provides a [Keycloak][keycloak] broker mapper that maps a
|
||||||
multivalued OIDC claim (e.g.: groups) or SAML attribute (e.g.: groupMembership)
|
multivalued OIDC claim (e.g.: groups) or SAML attribute (e.g.: groupMembership)
|
||||||
into one or more realm and/or client role assignments based on regular
|
into one or more realm and/or client role assignments based on regular
|
||||||
expressions.
|
expressions.
|
||||||
|
|
@ -29,7 +29,150 @@ Copy `keycloak-regex-mapper-«version».ear` to `${KEYCLOAK_HOME}/deployments`.
|
||||||
|
|
||||||
### configuration
|
### configuration
|
||||||
|
|
||||||
TODO
|
The _Advanced Claim to Role_ (OIDC) and _Advanced Attribute to Role_ (SAML) mappers included with
|
||||||
|
Keycloak provide a mechanism to map specific claim/attribute values to a specific target realm or
|
||||||
|
client. This can be tedious to configure if there are many target roles that should be mapped.
|
||||||
|
|
||||||
|
The purpose of the _Regex Realm and Client Role Importer_ mappers (one for OIDC, one for SAML)
|
||||||
|
included in this project is to provide a mechanism to map many entries in an OIDC claim
|
||||||
|
( e.g., `groups`) or SAML attribute (e.g.: `groupMembership`) to target roles using a single
|
||||||
|
configured mapper.
|
||||||
|
|
||||||
|
The mechanism relies on two principles:
|
||||||
|
|
||||||
|
* that the claim / attribute provider uses clientId and realmName values when naming things... in
|
||||||
|
other words, the mapping exists on the claim/attribute provider
|
||||||
|
* assigning an attribute to each realm and claim role to be managed by the mapper
|
||||||
|
|
||||||
|
#### OIDC Example
|
||||||
|
|
||||||
|
Suppose that the claim provider has a group structure as follows:
|
||||||
|
|
||||||
|
```
|
||||||
|
/IdentityBrokers
|
||||||
|
/idb1 # this is the realm
|
||||||
|
/Roles # these are the realm roles
|
||||||
|
SupportAnalyst # A
|
||||||
|
member=alice
|
||||||
|
member=bob
|
||||||
|
/ServiceProviders # these are the clients
|
||||||
|
/sp1 # B
|
||||||
|
/Roles # these are the client roles for sp1
|
||||||
|
Impersonator # C
|
||||||
|
member=alice
|
||||||
|
/sp2 # D
|
||||||
|
/Roles # these are the client roles for sp2
|
||||||
|
OtherRole # E
|
||||||
|
member=bob
|
||||||
|
```
|
||||||
|
|
||||||
|
Then, when Alice logs in to / through idb1, the `groups` claim would contain:
|
||||||
|
|
||||||
|
```
|
||||||
|
IdentityBroker/idb1/Roles/SupportAnalysts
|
||||||
|
IdentityBroker/idb1/ServiceProviders/sp1/Roles/Impersonator
|
||||||
|
```
|
||||||
|
|
||||||
|
Whereas Bob's would contain:
|
||||||
|
|
||||||
|
```
|
||||||
|
IdentityBroker/idb1/Roles/SupportAnalysts
|
||||||
|
IdentityBroker/idb1/ServiceProviders/sp2/Roles/OtherRole
|
||||||
|
```
|
||||||
|
|
||||||
|
At the identity broker, realm and client roles would be configured as follows:
|
||||||
|
|
||||||
|
```
|
||||||
|
Roles # these are the realm roles
|
||||||
|
SupportAnalyst # matches A above
|
||||||
|
Clients
|
||||||
|
sp1 # matches B above
|
||||||
|
Roles # these are the client roles for sp1
|
||||||
|
Impersonator # matches C above
|
||||||
|
attribute:
|
||||||
|
key="automatically mapped"
|
||||||
|
value="true"
|
||||||
|
sp2 # matches D above
|
||||||
|
Roles # these are the client roles for sp2
|
||||||
|
OtherRole # matches E above
|
||||||
|
attribute:
|
||||||
|
key="automatically mapped"
|
||||||
|
value="true"
|
||||||
|
```
|
||||||
|
|
||||||
|
And the _Regex Realm and Client Role Importer_ mapper would be configured as follows:
|
||||||
|
|
||||||
|
| configuration key | value |
|
||||||
|
| ------------------------------- | ------------------------------------------------------------------------ |
|
||||||
|
| type | `Regex Realm and Client Role Importer` |
|
||||||
|
| name | `groups to realm and client roles` |
|
||||||
|
| sync mode override | `force` |
|
||||||
|
| OIDC claim name | `groups` |
|
||||||
|
| client roles attribute name | `automatically mapped` |
|
||||||
|
| client roles regular expression | `/IdentityBrokers/idb1/ServiceProviders/(?<client>.*)/Roles/(?<role>.*)` |
|
||||||
|
| realm roles attribute name | `automatically mapped` |
|
||||||
|
| realm roles regular expression | `/IdentityBrokers/idb1/Roles/(?<role>.*)` |
|
||||||
|
|
||||||
|
The purpose of the the `client roles attribute name` and the `realm roles attribute name` is to flag
|
||||||
|
for the mapper which client and realm roles to assign / un-assign. Otherwise, every role not
|
||||||
|
matching the regular expressions would be un-assigned, including those that might have been locally
|
||||||
|
assigned by an administrator.
|
||||||
|
|
||||||
|
Take note of the named groupings (e.g.: `(?<client>.*)` in the regular expressions:
|
||||||
|
|
||||||
|
* the `client roles regular expression` needs two: `client` and `role`.
|
||||||
|
* The `realm roles regular expression` only needs one: `role`.
|
||||||
|
|
||||||
|
#### SAML example
|
||||||
|
|
||||||
|
Suppose the attribute provider draws group membership from an LDAP server structured as follows:
|
||||||
|
|
||||||
|
```
|
||||||
|
dc=example,dc=com
|
||||||
|
ou=IdentityBrokers
|
||||||
|
ou=idb1
|
||||||
|
ou=Roles # realm roles
|
||||||
|
cn=SystemAnalyst
|
||||||
|
member=alice
|
||||||
|
member=bob
|
||||||
|
ou=ServiceProviders
|
||||||
|
ou=sp1
|
||||||
|
ou=Roles # client roles for sp1
|
||||||
|
cn=Impersonator
|
||||||
|
member=alice
|
||||||
|
ou=sp2
|
||||||
|
ou=Roles # client roles for sp2
|
||||||
|
cn=OtherRole
|
||||||
|
member=bob
|
||||||
|
```
|
||||||
|
|
||||||
|
For Alice, groupMembership would contain:
|
||||||
|
|
||||||
|
```
|
||||||
|
cn=SystemAnalyst,ou=Roles,ou=idb1,ou=IdentityBrokers,dc=example,dc=com
|
||||||
|
cn=Impersonator,ou=Roles,ou=sp1,ou=ServiceProviders,ou=idb1,ou=IdentityBrokers,dc=example,dc=com
|
||||||
|
```
|
||||||
|
|
||||||
|
For Bob, groupMembership would contain:
|
||||||
|
|
||||||
|
```
|
||||||
|
cn=SystemAnalyst,ou=Roles,ou=idb1,ou=IdentityBrokers,dc=example,dc=com
|
||||||
|
cn=OtherRole,ou=Roles,ou=sp2,ou=ServiceProviders,ou=idb1,ou=IdentityBrokers,dc=example,dc=com
|
||||||
|
```
|
||||||
|
|
||||||
|
Assuming the same realm and client role configuration as above (in the OIDC example), then the _Regex
|
||||||
|
Realm and Client Role Importer_ mapper would be configured as follows:
|
||||||
|
|
||||||
|
| configuration key | value |
|
||||||
|
| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||||||
|
| type | `Regex Realm and Client Role Importer` |
|
||||||
|
| name | `groups to realm and client roles` |
|
||||||
|
| sync mode override | `force` |
|
||||||
|
| SAML attribute name | `groupMembership` |
|
||||||
|
| client roles attribute name | `automatically mapped` |
|
||||||
|
| client roles regular expression | `cn=(^<role>.*),ou=Roles,ou=(^<client>.*),ou=ServiceProviders,ou=idb1,ou=IdentityBrokers,dc=example,dc=com` |
|
||||||
|
| realm roles attribute name | `automatically mapped` |
|
||||||
|
| realm roles regular expression | `cn=(^<role>.*),ou=Roles,ou=idb1,ou=IdentityBrokers,dc=example,dc=com` |
|
||||||
|
|
||||||
## development
|
## development
|
||||||
|
|
||||||
|
|
@ -39,8 +182,8 @@ This project follows the module/bundle approach to packaging keycloak extensions
|
||||||
|
|
||||||
* `module` builds the jar that contains the keycloak extensions
|
* `module` builds the jar that contains the keycloak extensions
|
||||||
|
|
||||||
* `bundle` builds the ear that contains the jar from `module` and the jars for
|
* `bundle` builds the ear that contains the jar from `module` and any jars that are
|
||||||
any not-provided dependencies
|
not designated as `provided` dependencies
|
||||||
|
|
||||||
### coding conventions
|
### coding conventions
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue