Document toolboxDocument toolbox

Scopes and Claims

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.  

Note that the set of scopes and claims that an OIDC client may get access to is configured on a per-client basis as part of the provisioning process

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_access part 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.
ScopeDescriptionAPIResultFurther actions
openidUsed to get the minimum part of the ID Token. Can be used to authenticate users in an anonymous way.AuthorizeClaims in ID Token
profileUsed to enrich the ID Token with the end user's name and birthdate. Does not involve end user consent.AuthorizeClaims in ID Token
nnin_altsub

Used to enrich the ID Token with end user's national identity number. Does not involve end user consent.

Authorizennin_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.

bankid_proofUsed 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

bankid_proof in token response

See BankID Proof for more information.
chgpwdUsed to initiate an enduser change of password in the BankID WebClient. Authorizeno additional claims

The end user is prompted for a new password in the BankID Webclient after successfully authentication using the old password. 

  • This scope cannot be used together with the sign scope, that is considered an error.
  • Only supported when BankID Webclient is used.
  • If the Webclient is not used and scope contains "chgpwd" that is not considered an error. F.ex.: BID is not specified in login_hint and the end user selects BankID on Mobile.
  • When the end user is prompted for a new password, the end user may skip this by clicking a "Use old password" check box.
  • This scope has nothing to do with the administrator setting new password on the end user's BankID and demanding the end user to change on first use. That flow  does not have a "Use old password" check box.
  • The BankID OIDC client must be enabled for this 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


signUsed when initiating a signing transactionAuthorizeresource_access to SignDoc resource server, as part of the Access tokenClaims 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.

Authorizeresource_access to TINFO resource server, as part of the Access tokennnin 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.

Authorizeresource_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.

Authorizeresource_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.

Authorizeresource_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

AuthorizeToken

resource_access to AML resource server, as part of the Access token
aml_person/monitor
Tokenresource_access to AML resource server
aml_person/OFAC
AuthorizeTokenresource_access to AML resource server
aml_organization/basic
Tokenresource_access to AML resource server
aml_organization/monitor
Tokenresource_access to AML resource server
aml_organization/OFAC
Tokenresource_access to AML resource server
fraud-data-rs/GetSecurityData
Tokenresource_access to Fraud Data resource serverSee securityData
operational-status/read
Tokenresource_access to Operational Status resource server