See openid-connect Menu

Scopes

Scopes are a concept used in the OAuth 2.0 specification to specify the access privileges when issuing an Access Token.

As OpenId Connect (OIDC) is built upon OAuth 2.0 and has a notion of scopes, which in this case, specifies the information returned about the authenticated user.

In OIDC, the information for a specific scope is represented as a claim value in the JSON Web Token (JWT), aka ID Token, that’s returned after successful authentication, as well as via the UserInfo endpoint.

Standard Scopes

There are a set of standard scopes that return a collection of standard claims.

openid

required

integer

This is the only mandatory scope and will return a sub claim which represents a unique identifier for the authenticated user.

profile

string

This scope value requests access to the End-User’s default profile Claims, which are: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at.

Note, these claims are returned if OneLogin has the information available.

Example - Minimum required scope

When authenticating with the minimum requirement of using the openid scope the following ID Token will be returned.

{
  "sub": "35666371",
  "email": "styler@onelogin.com",
  "preferred_username": "Sally",
  "name": "Sally Tyler",
  "at_hash": "znht1pnyrypkT0KdL5HqQQ",
  "rt_hash": "bKEikCYYUi6nXf4GyGnrOA",
  "aud": "78d1d040-20c9-0136-5146-067351775fae92920",
  "exp": 1523664626,
  "iat": 1523657426,
  "iss": "https://openid-connect.onelogin.com/oidc"
}

Example - Getting user profile claims

If the scope is extended to include profile the ID Token will also contain a standard set of user profile attributes.

{
  "sub": "35666371",
  "email": "styler@onelogin.com",
  "preferred_username": "Sally",
  "name": "Sally Tyler",
  "updated_at": "2018-04-13T22:08:45Z",
  "given_name": "Sally",
  "family_name": "Tyler",
  "at_hash": "lPLhxI2wjEndc-WfyroDZA",
  "rt_hash": "mCmxPtA04N-55AxlEUbq-A",
  "aud": "78d1d040-20c9-0136-5146-067351775fae92920",
  "exp": 1523664997,
  "iat": 1523657797,
  "iss": "https://openid-connect.onelogin.com/oidc"
}

Groups Scope

Our OIDC implementation supports a special groups scope that provides role or group information for a user. This information is returned as an array, in a groups claim, and is used by APIs to restrict or control returned data.

Configure the Groups scope

Configure the Groups parameter for your OIDC app, in the OneLogin portal, to ensure the groups claim is returned.

It is common to map the Groups parameter to an Active Directory member_of field or simply map a users roles within OneLogin.

OIDC Parameters

Example - Mapping OneLogin Roles to Groups claim

Go to the Parameters tab of your OIDC app and select the Groups parameter to map the OneLogin roles a user is assigned to in the groups claim.

Groups Parameter

  1. In the Default if no value field, select User Roles.
  2. Select Semicolon Delimited input (Multi-value output) in the adjacent field.

When you request new OIDC authentication, and supply the groups scope, it returns a groupsclaim containing the user roles.

{
  "sub": "35666371",
  "email": "styler@onelogin.com",
  "preferred_username": "Sally",
  "name": "Sally Tyler",
  "updated_at": "2018-04-13T22:08:45Z",
  "given_name": "Sally",
  "family_name": "Tyler",
  "groups": [
    "Admin Role",
    "User Role",
    "Custom Roll"
  ],
  "at_hash": "lPLhxI2wjEndc-WfyroDZA",
  "rt_hash": "mCmxPtA04N-55AxlEUbq-A",
  "aud": "78d1d040-20c9-0136-5146-067351775fae92920",
  "exp": 1523664997,
  "iat": 1523657797,
  "iss": "https://openid-connect.onelogin.com/oidc"
}
If the user does not belong to any roles then the groups claim will not be returned.

Have a Question?

Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.

Found a bug? Submit a support ticket.

Have a product idea or request? Share it with us in our Ideas Portal.