Scopes and Claims#
The notions of scopes and claims are at the heart of OpenID Connect (opens in a new tab) and OAuth2 (opens in a new tab).
- A scope is a way for the Relying Party (merchant) to indicate to the OIDC Provider what service or data it requests access to.
- The response from a OIDC Provider consists of tokens with attributes on the user and the authentication event. The key/values in these tokens are referred to as claims.
The set of claims returned in a token response from the may differ from the set of claims that were requested:
- First, because an Relying Party may not be eligible to the full set of claims that are supported by BankID.
- Second, because the end-user may need to provide consent.
Supported scopes#
- Some scopes will result in ID Token claims (once the authorization code is exchanged for tokens)
- 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 | nnin_altsub can not be used to onboard new customers if you don't already possess their national identity number. For onboarding purposes, nnin must be used, which prompt end user consent for storing this data point. |
| nnin | Used to request access to end user's national identity number. This will prompt end user consent for sharing their data. (deprecated) | authorize | resource_access to TINFO resource server, as part of the Access token | nnin is downloaded through userinfo |
| bankid_proof | (Deprecated) Used to retrieve proof of BankID High authentication by including end user signature, OSCP response and information used to generate message digest signed by end-user. | authorize | bankid_proof in token response | 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 for a BankID High authentication. This scope cannot be used together with the sign scope. |
| signdoc/read_write | Used for creating and uploading a signing order to the SignDoc resource server through client credential grant. | token | resource_access to SignDoc resource server, as part of the Access token | |
| 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 signdoc/pades, depending on the solution |
| 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 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 userinfo This scope is in BETA phase and currently the end user experience is not optimal. |
| 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 userinfo This scope is in BETA phase and currently the end user experience is not optimal. | |
| aml_person/basic | Used to request access to AML data for a person. | authorize, token | resource_access to AML resource server, as part of the Access token | |
| aml_person/monitor | Used to request monitor access for a person. | token | resource_access to AML resource server | |
| aml_person/OFAC | Used to request OFAC access | authorize, token | resource_access to AML resource server | |
| aml_organization/basic | Used to request access to AML data for an organization. | token | resource_access to AML resource server | |
| aml_organization/monitor | Used to request monitor access for an organization. | token | resource_access to AML resource server | |
| operational-status/read | Used to request access to operational status data. | token | resource_access to Operational Status resource server |