authorization
- Kai Bjørnstad (Deactivated)
- Stine Granviken
The authorization endpoint is described in the OIDC specification:
For Authorization Code Flow: Authorization Endpoint - Code
For Implicit Flow: Authorization Endpoint - Implicit
For Hybrid Flow:Authorization Endpoint - Hybrid
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
https://auth.buypass.no/auth/realms/SECURITYDOMAIN/protocol/openid-connect/authAuthentication 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 | 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:
| 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 e.g. be the users 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 e.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. 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.
| 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 e.g. be values like "sc", "mobile" etc. The values are defined as part of the Security Domain. See https://tools.ietf.org/html/rfc8176 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 |
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:
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
Requirements:
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
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.