1. Home >
2. OpenId Connect >
3. Scopes

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 string	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.
phone string	Returns a phone_number claim.
offline_access string	Version 2.0 only. When this scope is supplied with Password Grant a refresh_token allowing offline access will be returned. Using this scope with Implicit or Authorization Code flow will cause an error.

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. See Introduction to User Provisioning in our Knowledge Base for more information on configuring parameters.

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

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.

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 groups claim 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"
}

Params Scope

When the params scope is supplied a params claim will be returned containing any arbitrary parameters that have been defined on the Parameters tab of an OIDC app.

Example

In this example we will map a custom External Id to a my_external_id value in the params claim.

1. Go to the Parameters tab of your OIDC app and click add parameter.
2. Give the parameter the name my_external_id. This will be the attribute name returned in the claim.
3. Map the new parameter to the External ID attribute.

When you request new OIDC authentication, and supply the params scope, it returns a params claim containing an attribute named my_external_id.

{
  "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",
  "params": {
    "my_external_id": "sf86122"
  },
  "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"
}

---