In this article, Janua’s CTO shares tips and tricks about understanding Oauth2-OpenID scope usage with Keycloak.
1) What are scopes used for ?
Scopes is basic feature of Identity and Access Management. Scopes are like a court yard.
Scopes allow to define and restrain a perimeter with resources (claims/attributes/roles) that applications are entitled to access :
- The perimeter accessible by apps is delimited by a list of scopes
- Each scope allows to define a list of attributes/roles (claims) that are exposed
- The way to use scopes is as follows :
- (1) Each application is defined with list of avalaible scopes by default
(This configuration part is provided once the application is registered with the Authorisation Server )
- (2) On Oauth2/openId request the list of all the scope to be requested has to be provided.
2) Oauth2penID Scope definition
2.1) Oauth2 scope definition
The RFC6749 provides teh following scope definition
3.3. Access Token Scope
The authorization and token endpoints allow the client to specify the scope of the access request using the “scope” request parameter. In turn, the authorization server uses the “scope” response parameter to inform the client of the scope of the access token issued.
2.2) OpenID scope definition
The openID scope definition is provided as follows :
5.4. Requesting Claims using Scope Values
OpenID Connect Clients use scope values, as defined in Section 3.3 of OAuth 2.0 [RFC6749], to specify what access privileges are being requested for Access Tokens. The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints. Protected Resource endpoints MAY perform different actions and return different information based on the scope values and other parameters used when requesting the presented Access Token.
- OpenID specification comes up with predefined set of scope such as profile, email, address
- Any openid request shoudl at least contains scope=openid within the request
3) Using scopes with Keycloak
Clients scopes allows you to define a common set of mappers and roles that are shared between multiple applications.
Using scopes with keycloak is achieved through the following steps
- (1) Create a new client scope within a realm
- (2) Add the mappers corresponding to this new scope
- (3) Add the new scope as client scope of the application
- (4) Perform requests using this new scope
3.2) Creating a new Client scope within a realm
A new client scope is created within a given realm.
Once created, this new scope appears in the list of available scopes within this realm
3.3) Adding Mappers to the client scope
Once created, the new client scope is like an empty nut. Mappers should be added to it, which will correspond to claims in the access token.
In the example provided here, the scope info will expose the token claim postal_code in the access_token
3.4) Adding the new client scope to the application
The application needs to be updated to acknowledge client scope usage
To become effective, this new scope has to be mentioned as an assigned optional client scope
3.5) Using new created scope in REST API query
To use the scope the API request should contain “scope=openid info”
-d "client_id=ldap-app" -d "client_secret=password" \
-d "username=jbrown" -d "password=password" \
-d "grant_type=password" \
-d "scope=openid info" \
https://localhost:8180/auth/realms/ldap-demo/protocol/openid-connect/token | jq -r '.access_token'`
curl --header "Authorization: Bearer $access_token" \
https://localhost:8180/auth/realms/ldap-demo/protocol/openid-connect/userinfo | jq .
"name": "James Brown",
- Understanding Oauth2-OpenID scope usage with Keycloak - 2 octobre 2019
- Using Impersonation with Keycloak - 13 septembre 2019
- Offline Sessions and Offline tokens within Keycloak - 28 août 2019