The recommended practise for merchants is to use the Authorize URL from Openid-configuration rather than hardcoding the below URL value.

URL	`https://<oidc-baseurl>/precheck/auth`
Request	`GET` with URL query parameters `POST` is not supported
Authentication	None
Success response	`303 See Other` with response elements added to redirect uri
Error response	`303 See Other` with standard error reponse elements added to redirect uri Other applicable http error code if redirect uri is missing, invalid or mismatching
Example	See below

Authorize is a standard endpoint that triggers authentication of an enduser via one of the IDP options, followed by authorization in terms of consent handling. Authorization information is then returned in the reponse to the requesting OIDC Client. The content of the authorization response is different for each of the supported message flows. The Authorize endpoint does in any case trigger a series of re-directs, eventually returning to the requesting OIDC Client at a redirect_uri specified by the client. For security reasons only pre-registered redirect URIs are allowed.

Request parameters

Name	Description
`scope`	List of scope values specifying what kind of resources (dataset) the OIDC Client requests access to. The value `openid` must always be included in the list. Each scope value must be separated by space. Scope values are case-sensitive.
`response_type`	Determines the message flow to be used, thus also governing the content and type of the response from the Authorize endpoint. The following combinations are supported: `"code"` (Authorization code flow) `"id_token"` or "`id_token token"` (Implicit flow) "`code id_token`", "`code token`", or "`code id_token token`" (Hybrid flow)
`client_id`	Unique ID (arbitrary string) for the OIDC Client in question. This is created as part of the provisioning process.
`redirect_uri`	Redirect URI to which the Authorize response will be sent. This URI must exactly match one of the Redirect URI values for the OIDC Client pre-registered at the OpenID Provider
`state`	Opaque value used to maintain state between the request and the callback.
`response_mode`	The response mode to be used for returning parameters from the Authorization Endpoint via `redirect_uri`. The following values are supported: `query` `fragment` `form_post`
`nonce`	String value used to associate a ODIC Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token
`ui_locales`	May be used to set a language preference for GUI handling. The default GUI experience supports 'nb' (Norsk Bokmål) and 'en' (English). If `ui_locales` is not set, the first (if any) `Accept-Language` header of the request is used to dermine preferred locale. Otherwise 'nb' is used by default.
`prompt`	Support for the standardized values `none` and `login`. The former can be used to check for an existing (still valid) authentication session with the OIDC provider. The latter can be used to force a re-authentication, possibly with a different `login_hint` and/or `acr_values.`
`acr_values`	Requests use of any IDP at a given Level of Assurance (Authentication Context Class Reference) or above. A selector dialogue is shown to the enduser if more than one IDP option meet the required minimum level. Note that this parameter has no effect if the `login_hint` parameter contains a reference to any particular IDP. Nor does it have any effect if the `id_token_hint` parameter is set. If none of these parameters are set a selector dialogue is shown contianing all available IDP options.
`login_hint`	This parameter may be used to specify the use of any particularly named IDP (Authentication Method Reference) along with any pre-configuration for the designated IDP. Note that this parameter has no effect f the `id_token_hint` parameter is set. If none of these parameter are set, the `acr_values` parameter determines IDP selection. See further details on login_hint support for each of the supported IDPs.
`id_token_hint`	JWT value for an ID Token previously issued by the OIDC Provider used as a hint about the enduser's authenticated session with the OIDC provider. Note that this parameter has precedence before both `acr_values` and `login_hint`, but precedence after the `prompt` parameter. If the ID Token has expired, a new authentication is triggered for the IDP option that was used when the ID Token was issued. Otherwise the authentication is still granted valid and the OIDC Provider proceeds directly to consent handling.

Note that the following set of standard parameters is currently not supported by the OpenID Connect Provider from BankID: display, max_age

Response elements

Responses are different for each of the supported message flows as specified by the response_type and response_mode parameters in the Authorize request.

Authorization Code flow

The standard response for this flow is to add relevant parameters as URL query-parameters to the redirect_uri,unless a different response_mode was specified. For this flow only code is returned in the Authorize response. The Token endpoint must be called to retrive id_token and access_token.

Implicit Flow

The standard response for this flow is to add relevant parameters to the fragment component of the Redirection URI, unless a different response_mode was specified. For this flow both id_token and access_token is returned directly in the Authorize response. The format of these tokens are the same as for tokens returned via the Token endpoint.

Hybrid Flow

The standard response for this flow is to add relevant parameters to the fragment component of the Redirection URI, unless a different response_mode was specified. For this flow code and id_token is returned in the Authorize response. The Token endpoint must be called to retrive access_token. The format of the id_token is the same as for tokens returned via the Token endpoint.

Example

The following example shows a request/response for the Authorize endpoint. The example is generated from Postman (which is configured as a client at the OIDC Provider) and correspons to an Authorize Code flow. The request contains all supported scopes (scope=openid profile nnin_altsub) in this example. The OIDC Provider responds with HTTP 302 to redirect the User-Agent to start IDP handling for BankID.

Authorize request

GET /auth/realms/preprod/protocol/openid-connect/auth?client_id=Postman&scope=openid%20profile%20nnin_altsub&state=10455063&redirect_uri=https%3A%2F%2Fwww.getpostman.com%2Foauth2%2Fcallback&response_type=code HTTP/1.1
Host: oidc-preprod.bankidapis.no
Connection: close
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36
Upgrade-Insecure-Requests: 1
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.8
Cookie: AUTH_SESSION_ID=bf0a4c9f-2d00-43d8-8288-01b83ab1e580.bai-pp-keyc1; KEYCLOAK_IDENTITY=eyJhbGciOiJIUzI1NiIsImtpZCIgOiAiMTljYzZlOWYtYzc1ZS00ZjU4LWI5YWMtM2MzYTgzNzY3M2E3In0.eyJqdGkiOiJmMmZjMjFlZC1jNzMwLTRkYWQtODE5Zi0wNTVmNzQ0ODYyNjkiLCJleHAiOjE1MTA4NzM2NDMsIm5iZiI6MCwiaWF0IjoxNTEwODM3NjQzLCJpc3MiOiJodHRwczovL29pZGMtcHJlcHJvZC5iYW5raWRhcGlzLm5vL2F1dGgvcmVhbG1zL3ByZXByb2QiLCJzdWIiOiJiM2Y0ZDkxOS04Y2M1LTQxM2MtOWUxMS0zYzJjNjc1YjJmOGYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiZjBhNGM5Zi0yZDAwLTQzZDgtODI4OC0wMWI4M2FiMWU1ODAiLCJyZXNvdXJjZV9hY2Nlc3MiOnt9fQ.HzAa0utvnYbReP0xGGcKrc69VL8SpSPfHrXJgSG_WiQ; KEYCLOAK_SESSION=preprod/b3f4d919-8cc5-413c-9e11-3c2c675b2f8f/bf0a4c9f-2d00-43d8-8288-01b83ab1e580

HTTP/1.1 303 See Other
Date: Thu, 16 Nov 2017 13:13:24 GMT
Server: WildFly/10
Cache-Control: no-store, must-revalidate, max-age=0
X-Powered-By: Undertow/1
Location: https://oidc-preprod.bankidapis.no/auth/realms/preprod/broker/composite/login?code=_F8cBc1k9Gtx4_YGLJ1VKFRMagikw6_GIXB_5GORGh4&client_id=Postman
Content-Length: 0
Set-Cookie: KC_RESTART=eyJhbGciOiJIUzI1NiIsImtpZCIgOiAiMTljYzZlOWYtYzc1ZS00ZjU4LWI5YWMtM2MzYTgzNzY3M2E3In0.eyJjaWQiOiJQb3N0bWFuIiwicHR5Ijoib3BlbmlkLWNvbm5lY3QiLCJydXJpIjoiaHR0cHM6Ly93d3cuZ2V0cG9zdG1hbi5jb20vb2F1dGgyL2NhbGxiYWNrIiwiYWN0IjoiQVVUSEVOVElDQVRFIiwibm90ZXMiOnsic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBubmluX2FsdHN1YiIsImlzcyI6Imh0dHBzOi8vb2lkYy1wcmVwcm9kLmJhbmtpZGFwaXMubm8vYXV0aC9yZWFsbXMvcHJlcHJvZCIsInJlc3BvbnNlX3R5cGUiOiJjb2RlIiwiY29kZV9jaGFsbGVuZ2VfbWV0aG9kIjoicGxhaW4iLCJyZWRpcmVjdF91cmkiOiJodHRwczovL3d3dy5nZXRwb3N0bWFuLmNvbS9vYXV0aDIvY2FsbGJhY2siLCJzdGF0ZSI6IjEwNDU1MDYzIn19.UTpw0_70QuUV_hYKtzwkmbtXHkjo-KHcfGWfxFizh3o; Version=1; Path=/auth/realms/preprod; Secure; HttpOnly
Via: 1.1 oidc-preprod.bankidapis.no
Connection: close

The following intermediate request/response pair shows how the User-Agent returns to the OIDC Provder after IDP handling for BankID. The OIDC provider responds with HTTP 302 to redirect the User-Agent to the OIDC client that originated the Authorize request (Postman in this case).

IDP handling

GET /auth/realms/preprod/broker/composite/login?code=_F8cBc1k9Gtx4_YGLJ1VKFRMagikw6_GIXB_5GORGh4&client_id=Postman HTTP/1.1
Host: oidc-preprod.bankidapis.no
Connection: close
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36
Upgrade-Insecure-Requests: 1
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.8
Cookie: AUTH_SESSION_ID=bf0a4c9f-2d00-43d8-8288-01b83ab1e580.bai-pp-keyc1; KEYCLOAK_IDENTITY=eyJhbGciOiJIUzI1NiIsImtpZCIgOiAiMTljYzZlOWYtYzc1ZS00ZjU4LWI5YWMtM2MzYTgzNzY3M2E3In0.eyJqdGkiOiJmMmZjMjFlZC1jNzMwLTRkYWQtODE5Zi0wNTVmNzQ0ODYyNjkiLCJleHAiOjE1MTA4NzM2NDMsIm5iZiI6MCwiaWF0IjoxNTEwODM3NjQzLCJpc3MiOiJodHRwczovL29pZGMtcHJlcHJvZC5iYW5raWRhcGlzLm5vL2F1dGgvcmVhbG1zL3ByZXByb2QiLCJzdWIiOiJiM2Y0ZDkxOS04Y2M1LTQxM2MtOWUxMS0zYzJjNjc1YjJmOGYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiZjBhNGM5Zi0yZDAwLTQzZDgtODI4OC0wMWI4M2FiMWU1ODAiLCJyZXNvdXJjZV9hY2Nlc3MiOnt9fQ.HzAa0utvnYbReP0xGGcKrc69VL8SpSPfHrXJgSG_WiQ; KEYCLOAK_SESSION=preprod/b3f4d919-8cc5-413c-9e11-3c2c675b2f8f/bf0a4c9f-2d00-43d8-8288-01b83ab1e580; KC_RESTART=eyJhbGciOiJIUzI1NiIsImtpZCIgOiAiMTljYzZlOWYtYzc1ZS00ZjU4LWI5YWMtM2MzYTgzNzY3M2E3In0.eyJjaWQiOiJQb3N0bWFuIiwicHR5Ijoib3BlbmlkLWNvbm5lY3QiLCJydXJpIjoiaHR0cHM6Ly93d3cuZ2V0cG9zdG1hbi5jb20vb2F1dGgyL2NhbGxiYWNrIiwiYWN0IjoiQVVUSEVOVElDQVRFIiwibm90ZXMiOnsic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBubmluX2FsdHN1YiIsImlzcyI6Imh0dHBzOi8vb2lkYy1wcmVwcm9kLmJhbmtpZGFwaXMubm8vYXV0aC9yZWFsbXMvcHJlcHJvZCIsInJlc3BvbnNlX3R5cGUiOiJjb2RlIiwiY29kZV9jaGFsbGVuZ2VfbWV0aG9kIjoicGxhaW4iLCJyZWRpcmVjdF91cmkiOiJodHRwczovL3d3dy5nZXRwb3N0bWFuLmNvbS9vYXV0aDIvY2FsbGJhY2siLCJzdGF0ZSI6IjEwNDU1MDYzIn19.UTpw0_70QuUV_hYKtzwkmbtXHkjo-KHcfGWfxFizh3o

HTTP/1.1 303 See Other
Date: Thu, 16 Nov 2017 13:13:37 GMT
Server: WildFly/10
X-Powered-By: Undertow/1
Location: https://oidc-ui-preprod.bankidnorge.no/?client_id=Postman&state=eJJbjoA0srfihXvk5d1-UDf_8L1JwCJR8YTuauvP-cA.Postman&application_name=Postman&redirect_uri=https%3A%2F%2Foidc-preprod.bankidapis.no%2Fauth%2Frealms%2Fpreprod%2Fbroker%2Fcomposite%2Fendpoint&ui_locales=en&merchant_name=bankidexamples&nnin_req=true
Content-Length: 0
Via: 1.1 oidc-preprod.bankidapis.no
Connection: close

The following request/response pair shows how the originating OIDC Client (Postman in this case) resumes control in terms of a response from the OIDC Provider.

Return of control

GET /auth/realms/preprod/broker/composite/endpoint?state=eJJbjoA0srfihXvk5d1-UDf_8L1JwCJR8YTuauvP-cA.Postman&code=656cfe0c-32b2-4222-ad6f-089d76dc5b32 HTTP/1.1
Host: oidc-preprod.bankidapis.no
Connection: close
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8
Referer: https://oidc-ui-preprod.bankidnorge.no/view?sid=7bcc1515-25c4-4d42-8669-81f5898e0133
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.8
Cookie: AUTH_SESSION_ID=bf0a4c9f-2d00-43d8-8288-01b83ab1e580.bai-pp-keyc1; KEYCLOAK_IDENTITY=eyJhbGciOiJIUzI1NiIsImtpZCIgOiAiMTljYzZlOWYtYzc1ZS00ZjU4LWI5YWMtM2MzYTgzNzY3M2E3In0.eyJqdGkiOiJmMmZjMjFlZC1jNzMwLTRkYWQtODE5Zi0wNTVmNzQ0ODYyNjkiLCJleHAiOjE1MTA4NzM2NDMsIm5iZiI6MCwiaWF0IjoxNTEwODM3NjQzLCJpc3MiOiJodHRwczovL29pZGMtcHJlcHJvZC5iYW5raWRhcGlzLm5vL2F1dGgvcmVhbG1zL3ByZXByb2QiLCJzdWIiOiJiM2Y0ZDkxOS04Y2M1LTQxM2MtOWUxMS0zYzJjNjc1YjJmOGYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiZjBhNGM5Zi0yZDAwLTQzZDgtODI4OC0wMWI4M2FiMWU1ODAiLCJyZXNvdXJjZV9hY2Nlc3MiOnt9fQ.HzAa0utvnYbReP0xGGcKrc69VL8SpSPfHrXJgSG_WiQ; KEYCLOAK_SESSION=preprod/b3f4d919-8cc5-413c-9e11-3c2c675b2f8f/bf0a4c9f-2d00-43d8-8288-01b83ab1e580; KC_RESTART=eyJhbGciOiJIUzI1NiIsImtpZCIgOiAiMTljYzZlOWYtYzc1ZS00ZjU4LWI5YWMtM2MzYTgzNzY3M2E3In0.eyJjaWQiOiJQb3N0bWFuIiwicHR5Ijoib3BlbmlkLWNvbm5lY3QiLCJydXJpIjoiaHR0cHM6Ly93d3cuZ2V0cG9zdG1hbi5jb20vb2F1dGgyL2NhbGxiYWNrIiwiYWN0IjoiQVVUSEVOVElDQVRFIiwibm90ZXMiOnsic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBubmluX2FsdHN1YiIsImlzcyI6Imh0dHBzOi8vb2lkYy1wcmVwcm9kLmJhbmtpZGFwaXMubm8vYXV0aC9yZWFsbXMvcHJlcHJvZCIsInJlc3BvbnNlX3R5cGUiOiJjb2RlIiwiY29kZV9jaGFsbGVuZ2VfbWV0aG9kIjoicGxhaW4iLCJyZWRpcmVjdF91cmkiOiJodHRwczovL3d3dy5nZXRwb3N0bWFuLmNvbS9vYXV0aDIvY2FsbGJhY2siLCJzdGF0ZSI6IjEwNDU1MDYzIn19.UTpw0_70QuUV_hYKtzwkmbtXHkjo-KHcfGWfxFizh3o

HTTP/1.1 302 Found
Date: Thu, 16 Nov 2017 13:14:10 GMT
Server: WildFly/10
X-Powered-By: Undertow/1
P3P: CP="Dette er ikke en P3P policy!"
Location: https://www.getpostman.com/oauth2/callback?state=10455063&code=uss.iq5WXmK5dDQCprQn8kMz_EIiBrAYA0hxOc9jZM0pZfo.bf0a4c9f-2d00-43d8-8288-01b83ab1e580.1714e8ff-0adf-449f-8c50-bf0a77617a43
Content-Length: 0
Set-Cookie: KC_RESTART=; Version=1; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Max-Age=0; Path=/auth/realms/preprod; Secure; HttpOnly
Set-Cookie: KEYCLOAK_IDENTITY=eyJhbGciOiJIUzI1NiIsImtpZCIgOiAiMTljYzZlOWYtYzc1ZS00ZjU4LWI5YWMtM2MzYTgzNzY3M2E3In0.eyJqdGkiOiI5OTM2YjU3Ny1jMmYxLTQzOGMtYmU2Yy02MGU2ZTNkMmI0YjEiLCJleHAiOjE1MTA4NzQwNTAsIm5iZiI6MCwiaWF0IjoxNTEwODM4MDUwLCJpc3MiOiJodHRwczovL29pZGMtcHJlcHJvZC5iYW5raWRhcGlzLm5vL2F1dGgvcmVhbG1zL3ByZXByb2QiLCJzdWIiOiJiM2Y0ZDkxOS04Y2M1LTQxM2MtOWUxMS0zYzJjNjc1YjJmOGYiLCJhdXRoX3RpbWUiOjAsInNlc3Npb25fc3RhdGUiOiJiZjBhNGM5Zi0yZDAwLTQzZDgtODI4OC0wMWI4M2FiMWU1ODAiLCJyZXNvdXJjZV9hY2Nlc3MiOnt9fQ.cqfcW3aYEGXdqYHhYsAOWZNQkjIfuL5UjhXH3xpJCQw; Version=1; Path=/auth/realms/preprod; Secure; HttpOnly
Set-Cookie: KEYCLOAK_SESSION=preprod/b3f4d919-8cc5-413c-9e11-3c2c675b2f8f/bf0a4c9f-2d00-43d8-8288-01b83ab1e580; Version=1; Expires=Thu, 16-Nov-2017 23:14:10 GMT; Max-Age=36000; Path=/auth/realms/preprod; Secure
Set-Cookie: KEYCLOAK_REMEMBER_ME=; Version=1; Comment=Expiring cookie; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Max-Age=0; Path=/auth/realms/preprod; Secure; HttpOnly
Via: 1.1 oidc-preprod.bankidapis.no
Connection: close

For an Authorize Code flow as used by the OIDC Client (Postman) in this case, the Client sits with an authorization code that needs to be passed on to the Token endpoint to retrieve a set of tokens (ID Token, Access Token and Refresh Token.