Understanding Oauth2-OpenID scope usage with Keycloak

par | Oct 2, 2019 | Communauté, Gestion des Identités, SSO

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

https://tools.ietf.org/html/rfc6749#section-3.3
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 :

https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims

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

3.1) Presentation

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.

Understanding Oauth2/openID scope usage with Keycloak

Once created, this new scope appears in the list of available scopes within this realm

Understanding Oauth2/openID scope usage with Keycloak
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 »

 access_token=`curl \
 -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 .
 {
   "sub": "e94eebf2-48fe-4a1d-b1c5-12d7018f6f7a",
   "email_verified": false,
   "name": "James Brown",
   "preferred_username": "jbrown",
   "postal_code": [
     "88441"
   ],
   "given_name": "James",
   "family_name": "Brown",
   "email": "jbrown@keycloak.org"
janua
Les derniers articles par janua (tout voir)