Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

...

...

...

Table of Contents

The authorization endpoint is described in the OIDC specification:

The endpoint is also described (in a generic manner) in the OAuth2 specification: Authorization Endpoint - OAuth2.

The flow used is determined by the response_type

...

parameter value contained in the Authorization Request, see below.

Endpoint URL

The authorization endpoint URL can be found by looking at the value of the "authorization_endpoint" key in the openid-configuration.

Typical format of the URL is:

...

...

Authorization Endpoint URL - Example format
Code Block
languagexml
https://auth.buypass.no/auth/realms/SECURITYDOMAIN/protocol/openid-connect/auth

Authentication Request

An authentication request requests that the end-user be authenticated by

...

the OpenID Provider.

...

 All parameters should be on the format "application/x-www-form-urlencoded".

Note that the request does not require client authentication, but the client_id and redirect_uri parameters must be registered with

...

the OpenID Provider.

Required request parameters

Parameter

Description

Example

scope

Requests must contain the openid scope value.

Other scope values may be present, but will only be interpreted in the context of a Security Domain.

See Scopes for additional scope values defined by the specification and supported by Buypass.

scope=openid

response_type

The response type value determines the authorization processing flow to be used (see also Authentication with OIDC), including what parameters are returned from the endpoints used:

response_type=code

Trigger Authorization Code Flow. Process returns one time code to client.

response_type=id_token

Trigger Implicit Flow. Process returns ID Token to client.

response_type=id_token token

Trigger Implicit Flow. Process returns ID Token and Access Token to client.

response_type=code

client_id

See Client authentication

client_id=my-client

redirect_uri

Redirection URI to which the response will be sent.

This URI must exactly match one of the redirection URIs registered for the client with registration of the client in the Buypass OpenID Provider.

This URI should normally be a https-url.

redirect_uri=https%3A%2F%2Fapp.customer.com%2Fcurl-client%2Fcb

state

Recommended.

Opaque value used to maintain state between the request and the callback. The state parameter is an authentication parameter used to help mitigate CSRF attacks.

state=3c725e0151db3

Optional request parameters

Parameter

Description

Example

response_mode

Informs the OpenID Provider of the mechanism to be used for returning parameters from the endpoint.

See the value of the "response_modes_supported" key in the openid-configuration for available values.

response_mode=query

nonce

String value used to associate a 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.

nonce=abefb10d2b1b

display

Specifies how the OpenID Provider displays the authentication and consent user interface pages to the end-user.

NOTE: This parameter will have limited support and only be defined per service/domain/customer.

display=page

prompt

Specifies whether the OpenID Provider prompts the end-user for reauthentication and consent. This parameter may be useful for services running in an SSO scenario and authentication should be forced. The value may be a space separated list.

Available values are:

  • none : Do not display any authentication or consent user interface pages

  • login :

Prompt
  • Prompt the End-User for reauthentication

  • consent :

Prompt
  • Prompt the end-user for consent before returning information to the client

  • select_account :

Prompt
  • Prompt the End-User to select a user account

prompt=login consent

max_age

Not currently in use.


ui_locales

A space-separated list of the end-user's preferred language and scripts tag values, ordered by preference.

The tags should be according to Tags for Identifying Languages.

ui_locales=nb-NO en-US

id_token_hint

ID Token previously issued by the OpenID Provider being passed as a hint about the end-user's current or past authenticated session with the client.

id_token_hint=<ID Token JWT>

login_hint

Hint to the OpenID Provider about the login identifier the end-user might use to log in (if necessary). The hit may

f

e.

ex

g. be the users

phonenumber

phone number, email or Buypass ID.


login_hint=someuserid

acr_values

✋ This open standard request parameter is ignored by Buypass.

Space-separated string that specifies the acr values that the OpenID Provider is being requested to use for processing this authentication request.

In short: this value describes the clients requirements (represented as an agreed value) for the level of assurance/authentication it requires. The values can

f

e.

ex

g. be values like 1,2 or 3 or something like the eIDAS assurance levels: low, substantial and high.

NOTE: This parameter will have limited support and only be defined per service/domain/customer.

Se

See also Authentication methods and levels

💡 Even if the request parameter acr_values is ignored the value returned in the acr claim in the ID token will always be "acr": "eidas-loa-high".

Level high is the only level offered by Buypass at present.

acr_values=1 2

amr_values

✋ This open standard request parameter is ignored by Buypass.
Instead see the customized request parameter bp_amr_values.

Space-separated string that specifies the amr values that the OpenID Provider should use when selecting authentication methods.

In short this value enables dynamic control of the authentication methods to be used in this session. The values can

f

e.

ex

g. be values like "sc", "mobile" etc. The values are defined as part of the Security Domain. 

See 

See https://tools.ietf.org/html/rfc8176

 for

 for standardised values.

NOTE: This parameter will have limited support and only be defined per service/domain/customer.

Se also Authentication methods and levels

amr_values=sc, mobile

Example request

...

languagebash
themeMidnight
titleExample authentication request

bp_idp_hint

This parameter will give the possibility to access the Fido2 authentication-dialog directly for a User connected to an organisation issuing Buypass ID Fido2 for their employees.

Requirements:

  • Parameter is available in the Buypass ID security domain with the ID Broker flow only (ID Broker Service)

  • Parameter is used for authentication with BpID Fido2 only

  • A valid “tenantID” (reference to organisation) must be provided. A list of valid tenantIDs will be given on request to Buypass

💡 If both the parameters bp_idp_hint and bp_amr_values are requested - see explanation below.

bp_idp_hint=buypass

bp_amr_values

This parameter will give the possibility to select authentication method. By requesting an authentication method, the end user will be redirected directly to the chosen method and the menu options will disappear.

Values: sc, mobile or pwd_otp

  1. sc = Buypass ID on smartcard (PKI)

  2. mobile = Buypass ID on mobile with mobile app (PKI)

  3. pwd_otp = Buypass ID on mobile with password and otp on SMS (PKI)

Requirements:

  • Parameter is available in the Buypass ID security domain with the ID Broker flow only (ID Broker Service)

  • This is a single value option. If several values are sent the first will be chosen, or if invalid the end user will be presented the full menu.

💡 The input value is NOT returned in the amr or the bp_amr claim in the ID-token.

💡 If both the parameters bp_idp_hint and bp_amr_values are requested the parameter bp_idp_hint will have priority. If tenantID given is not known or invalid the bp_idp_hint parameter is ignored and the parameter in bp_amr_values taken into account. If authenticator value given is not known or invalid the end user will be presented the full menu and need to choose authenticator himself.

bp_amr_values=sc

Example request

Example authentication request
Code Block
languagebash
BASEURL="https://auth.buypass.no/auth/realms/SECURITYDOMAIN/protocol/openid-connect";
CLIENT_ID="oidc-client"


curl -i -w "\n" \
-H "Content-Type: application/x-www-form-urlencoded" \
-X GET "${BASEURL}/auth"\
"?scope=openid"\
"&response_type=code"\
"&client_id=${CLIENT_ID}"\
"&redirect_uri=https%3A%2F%2Fapp.examle.com%2Foidc-client%2Fcb"\
"&state=3c725e0151db3"

Authentication Response

Note that the HTTP response immediately following the authentication request may vary. The reason for this is that the immediate response may be the initiation of the authentication method. The response might be a HTML page requesting username and password, a redirect to another IdP or the start of some other dialogue for doing the actual end-user authentication.

In other words, the immediate HTTP response might not be the authentication response, And this varies with the setup.

But eventually, when the authentication method is completed, the actual authentication response will follow. The format of the authentication response will vary depending on

...

the authorization processing flow selected (determined by the response_type in the authentication request).

Authorization Code Flow

For the authorization code flow, response parameters are returned as query parameters to the redirect_uri specified in the authorization request. See also Successful authentication response - Code.

The code-parameter is used towards the token

...

 endpoint to retrieve the requested tokens.

Errors are handled according to the specification: Authentication error response.

Implicit Flow

For the implicit flow, response parameters are returned as query parameters to the redirect_uri specified in the authorization request. See also Successful authentication response - Implicit.

The response parameters include one or more tokens, making the explicit call to the token

...

 endpoint unnecessary.

Errors are handled according to the specification and done in the same way as for Authorization Code Flow: Authentication error response.

Hybrid Flow

For hybrid flow, authentication responses are made in the same manner as for the implicit flow (query parameters to the redirect_uri).

...

 See also Successful authentication response - Hybrid.

The response parameters include one or more tokens, but may also include a code-parameter. The code-parameter is used towards the token

...

 endpoint to retrieve the requested tokens.

Errors are handled according to the specification and done in the same way as for Authorization Code Flow: Authentication error response.

Other examples

Se also Authorization Examples.