You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

The REST API for the OIDC Provider from BankID consists of the following end-points according to the OpenID Connect and OAuth2 Standards.  

Refresh token

 (Note: the OIDC Service does currently not support refresh_tokens)

Configuration meta data.

https://preprod.bankidapis.no/oidc/oauth/.well-known/openid-configuration

Anonymous requests are allowed.

This end-point returns a JSON-formatted response containing key properties of the OIDC Provider.

Among other things this end-point is used to prepare for token validation.

Below is an example response from /openid-configuration for the OIDC Provider in its BankID configuration in pre-production:

{
"issuer":"https://preprod.bankidapis.no",
"authorization_endpoint":"https://preprod.bankidapis.no/oidc/oauth/authorize",
"token_endpoint":"https://preprod.bankidapis.no/oidc/oauth/token",
"userinfo_endpoint":"https://preprod.bankidapis.no/oidc/oauth/userinfo",
"jwks_uri":"https://preprod.bankidapis.no/oidc/oauth/userinfo/jwk",
"scopes_supported":[
"standard_bankid", "address", "phone",
"nnin", "openid", "profile",
"email"
],
"response_types_supported":[
"code", "token", "id_token",
"id_token token", "code token", "code id_token",
"code id_token token"
],
"response_modes_supported":[
"query", "fragment", "form_post"
],
"grant_types_supported":[
"authorization_code"
],
"subject_types_supported":[
"public"
],
"id_token_signing_alg_values_supported":[
"RS256"
],
"userinfo_signing_alg_values_supported":[
"RS256", "none"
],
"token_endpoint_auth_methods_supported":[
"client_secret_post", "client_secret_basic"
],
"claim_types_supported":[
"normal"],
"claims_supported":[
"preferred_username", "name", "sub",
"iat", "iss", "auth_time",
"exp", "birthdate", "nonce",
"amr", "azp", "bid_code",
"aud", "at_hash", "c_hash",
"nnin", "address", "phone"
],
"claims_parameter_supported":false,
"ui_locales_supported":[
"no",
"en"
],
"login_hint_supported":"[BIM|BID][:\\d{11}][:\\d{8}][:\\d{6}] for respectively client_type, nnin, phoneNo, birthday",
"serverVersion":"bankid-oauth-api 1.2.0"
}

Getting keys to sign tokens

https://preprod.bankidapis.no/oidc/oauth/userinfo/jwk

Anonymous requests are allowed.

This end-point returns the public part of keys used for signing tokens. The keys are later used for token validations. 

Example response from /jwk:

{
   "keys":[
   {
      "kty":"RSA",
      "n":"khw6L8E9GwwTu5AUclp (abbreviated ...) OM0MdzrKLLrmgiYVi",
      "e":"AQAB",
      "kid":"bankid-oauth",
      "use":"sig"
   }
 ]
}

Authentication and authorization

https://preprod.bankidapis.no/oidc/oauth/authorize

This is a browser redirect end-point that is thoroughly described in the OIDC/OAUTH2 standards. The following query parameters pertaining to the OIDC Provider can be used:

  1. Send an authorization request to OIDC Provider and wait for response on the redirectURL address. A scope parameter supplied with the request should contain "openid" and response type should contain "id_token", The id_token is as JSON structure containing user info from the authentication. The request may optionally include a login_hint to request as specific type of IDP, (e.g. netcentric or mobile for BankID) and/or to pre-feed any user-id that the end used would otherwise need to type in (eg. National Identity Numer and/or Mobile Number in the case of BankID).
  2. The OIDC Provider returns with a response back to the Client after the autentication of the end user. The response body should contain the id_token. 
  3. The OIDC Client now has the identity and other selected properties of the current user. The property/claim named "sub" contains a unique GUID of the current user (also referred to as BankID PID or SERIAL)

Note: Id_tokens should be validated for security reasons. There are several frameworks for working with OIDC. Some fameworks have automatic support for validating the id_token before getting access to it, and some publish example code for doing so. The published examples may be used as a template.

ParameterComment
client_idThis is a unique ID provided by BankID Norge for the calling OIDC Client.
scope

The discovery endpoint (see example above) returns

"scopes_supported":[
"standard_bankid", "address", "phone",
"nnin", "openid", "profile",
"email"
],

profile and email are part of the standard scopes, but are currently not supported by OIDC Provider

address and phone is supported if the Client is configured to allow for such information.

nnin - the Norwegian National Identiy Number (fødselsnummer) is supported as additional info if the Client is configured to allow for this information.

standard_bankid scope is used for clients with default scope of nnin, but currently don’t want nnin to be added in the UserInfo response.

response_type

Three combinations (associated with OAuth2 hybrid grant flows) are currently supported. Other combinations associated with other OAuth2 flows will be added as future options.

    • code - for clients that do not need to know the identity of its users, but need access_token for calling resource servers.
    • id_token - for clients that doesn't need an access_token to call UserInfo. Only an id_token is returned to the authorise request. (OIDC hybrid flow).
    • code id_token - here the client will receive both an authorization_code and an id_token. The authorization_code sent to the Token endpoint to retrieve an access_token to be used for UserInfo.
response_mode

This is how the response redirect is done. These alternatives are supported: query, fragment, form_post.

Note: The .NET/C# example GitHub uses the OWIN framework. OWIN only accepts form_post response mode.

login_hint

This parameter may be used to set choice of authentication

(netcentric or mobile) and, if known to the Client, nnin, mobile phone no, or birthday of the user.

An emtpy login hint implies that the default (or customized) GUI takes care of all interaction with the end-user to determine necessary login details.

The discovery/metadata endpoint returns: "login_hint_supported":"[BIM|BID][:\\d{11}][:\\d{8}][:\\d{6}] for respectively client_type, nnin, phoneNo, birthday"

Here are some examples with explanation:

  1. Netcentric BankID with user-profile - login_hint=BID:07025312345 (Norwegian national ID number/fødselsnummer)
  2. Netcentric BankID no user-profile - login_hint=BID
  3. BankID on mobile no user-profile - login_hint=BIM
  4. BankID on mobile with user-profile - login_hint=BIM:48058567:070253 (phone no and birthday DDMMYY)
  5. Some user-profile no BankID choice - login_hint=:07025312345  (numbers start with colon!)

In example no 5 the user is prompted for choice of BankID version, but Norwegian national number is used for BID and birthday is used for BIM (first 6 digits).

ui_localesMay be used to set a language preference for GUI handling. The default GUI experience supports nb (Norsk Bokmål) and en (English)


Note: When response_type contains both id_token and code, the authorization_code is duplicated into bid_code claim in the id_token to avoid conflict with authorization_code issued by AzureAD B2C. AAD must copy the claims from BankID OIDC id_token to the one issued by AAD. The client must get an access_token from the token end-point of the BankID OIDC Service in order to use resources managed by this service. This includes the UserInfo end-point.

Below is an example id_token as returned from the OIDC Provider in its current BankID Configuration in pre-production:

{
"kid":"bankid-oauth",
"typ":"JWT",
"alg":"RS256"
}.{
"preferred_username":"Testesen, Test",
"name":"Testesen, Test",
"given_name":"Test",
"family_name":"Testesen",
"sub":"9578-6000-4-127698",
"iat":1485863742,
"iss":"https://preprod.bankidapis.no",
"auth_time":1485863742,
"exp":1485867342,
"birthdate":"1980-03-09",
"nonce":"63621460527719310(abriviated for display)c0NDk1NDIz",
"amr":["BankID"],
"azp":"DotNetClient",
"aud":"DotNetClient",
"c_hash":"SVJo7O-d4cY8N4VgiVwETQ"
}

Token

https://preprod.bankidapis.no/oidc/oauth/token

Requires basic authentication with client_id and client_secret in the Autorization header,

This end-point is used for exchanging an authorization_code with an access_token. The access_token is used for accessing resources like userinfo and potential other resource servers. The access_code exchanged was created by the authorization endpoint with a response_type containing "code"

The request should be a POST with parameters sent as "application/x-www-form-urlencoded" data.

Input:

  • code=<value from authorization>
  • grant_type=authorization_code
  • redirect_uri=<redirect_uri used in authorization request>

Return is a JSON structure with name/value pairs.

 

  1. An access_token is required to enable the OIDC Client to get Additional Information by requesting the UserInfo endpoint. This currently only concerns the Norwegian National Identity Number (nnin) in case of BankID. To get access to nnin  the authorization request scope must contain "nnin" and return type should be "code id_token". The response body, from point 2, will additionally contain an autorization_code. This authorization_code is used to call the Token endpoint (client_id and client_secret is used for basic authentication of the request) to obtain an access_token.
  2. Use the access_token in the authorization header as a "Bearer" token to request the UserInfo endpoint. The response will contain a JSON structure which is much like the id_token, but with addition of "nnin" (client must be approved to use scope "nnin").

Retrieve UserInfo

https://preprod.bankidapis.no/oidc/oauth/userinfo

BankID OIDC has implemented an UserInfo enpoint. It is implemented as a resource server and expects an access_token as a Bearer token. There are no parameters. This service is the only way to get the nnin (fødselsnummer) of the authenticated user.

Example response from /userInfo:

{
"sub": "9578-6000-4-127698",
"iss": "https://preprod.bankidapis.no",
"iat": 1485866449,
"exp": 1485870048,
"preferred_username": "Testesen, Test",
"name": "Testesen, Test",
"given_name": "Test",
"family_name": "Testesen",
"birthdate": "1980-03-09",
"nnin": "09038000010"
}

Validate access_token - introspect

https://preprod.bankidapis.no/oidc/oauth/introspect

The introspect endpoint is thoroughly described in the OIDC/OAUTH2 standards. It is used by resource servers to validate access_tokens received in the authorize header from a client.

In return the resource server get claims from the access_token including its expiration time. The return is in JSON form with a list of name/value pairs.

  • No labels