Scopes and Claims
- Kristoffer Kristoffer (Unlicensed)
- Matheus Srebro
- Janny Kinende
Introduction
The notions of Scopes and Claims are at the heart of OpenID Connect and OAuth2.
- A scope is a way for the OIDC Client to indicate to the OIDC Provider what service it requests access to, or in technical terms which resources at pertinent Resource Servers. The response from a Resource Server consists of datasets with attributes on the user and/or the authentication event.
- Members of such a dataset are referred to as claims.
A Scope in OIDC can, therefore, be thought of as a shorthand for a larger pre-defined bundle of Claims. An OIDC Client may also request individual Claims, or any set of Claims, for fine-grained access.
The set of Claims returned to an OIDC Client in a response from the OIDC Provider may differ from the set of Claims that were requested. First, because an OIDC Client may not be eligible to the full set of claims that are supported by the BankID OIDC Provider. Second, because the end-user is always in control via consent handling.
The content of the ID Token that is returned in response to a successful authentication (or session refresh) is governed by the standard scopes openid and profile. These scopes are available to any OIDC Client. Some additional content is governed by custom scopes defined by the OIDC Provider from BankID, among them the Norwegian National Identity Number (nnin) that can be made available to eligible OIDC Clients. See the description of ID Tokens for further information.
Scopes and claims beyond those associated with ID Tokens are used to request Access Tokens (with corresponding Refresh Tokens) of the right kind for subsequent access to various resources at supported resource servers.
The scope named offline_access is a standard scope with implication on session handling. See also the description on Refresh Token for further information on the effect of this particular scope.
Supported scopes in the BankID OIDC Provider
Below we've listed all scopes supported by the BankID OIDC Provider. Note that
- Some scopes will result in ID Token claims (once the authorization code is exchanged for tokens)
- Some scopes will result in additional tokens in token response, i.e. bankid_proof.
- Some scopes will result in a
resource_accesspart in the Access Token (once the authorization code is exchanged for tokens). This is needed when downloading the actual results (claims) from the designated resource servers, using this Access token as a bearer token. - Some scopes will result in specific flows, i.e. sign, chgpwd.
| Scope | Description | API | Result | Further actions |
|---|---|---|---|---|
openid | Used to get the minimum part of the ID Token. Can be used to authenticate users in an anonymous way. | Authorize | Claims in ID Token | |
profile | Used to enrich the ID Token with the end user's name and birthdate. Does not involve end user consent. | Authorize | Claims in ID Token | |
nnin_altsub | Used to enrich the ID Token with end user's national identity number. Does not involve end user consent. | Authorize | nnin_altsub as part of ID Token |
|
bankid_proof | Used to retrieve proof of BankId Netcentric or BankID on Mobile authentication by including end user signature, OSCP response and information used to generate message digest signed by end-user. | Authorize |
| See BankID Proof for more information. |
| chgpwd | Used to initiate an enduser change of password in the BankID WebClient. | Authorize | no additional claims | The end user is prompted for a new password in the BankID Webclient after successfully authentication using the old password.
|
signdoc/read_write | Used for creating and uploading a signing order to the SignDoc resource server through client credential grant. |
| ||
sign | Used when initiating a signing transaction | Authorize | resource_access to SignDoc resource server, as part of the Access token | Claims are downloaded through signdoc or signdocpades, depending on the solution |
nnin | Used to request access to end user's national identity number. This will prompt end user consent for sharing their data. | Authorize | resource_access to TINFO resource server, as part of the Access token | nnin is downloaded through api-userinfo |
address | Used to request access to end user's address. This will prompt end user consent for sharing their data. | Authorize | resource_access to TINFO resource server, as part of the Access token | Claims are downloaded through api-userinfo This scope is in BETA phase and currently the end user experience is not optimal. |
phone | Used to request access to end user's phone number. This will prompt end user consent for sharing their data. | Authorize | resource_access to TINFO resource server, as part of the Access token | Claims are downloaded through api-userinfo This scope is in BETA phase and currently the end user experience is not optimal. |
email | Used to request access to end user's email address. This will prompt end user consent for sharing their data. | Authorize | resource_access to TINFO resource server, as part of the Access token | Claims are downloaded through api-userinfo This scope is in BETA phase and currently the end user experience is not optimal. |
aml_person/basic | resource_access to AML resource server, as part of the Access token | |||
aml_person/monitor | Token | resource_access to AML resource server | ||
aml_person/OFAC | Authorize, Token | resource_access to AML resource server | ||
aml_organization/basic | Token | resource_access to AML resource server | ||
aml_organization/monitor | Token | resource_access to AML resource server | ||
aml_organization/OFAC | Token | resource_access to AML resource server | ||
fraud-data-rs/GetSecurityData | Token | resource_access to Fraud Data resource server | See securityData | |
| operational-status/read | Token | resource_access to Operational Status resource server |