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 authorization.
Typical format of the URL is:
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 authorization 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 authorization), 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 authorization | 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 f.ex. be the users phonenumber, email or Buypass ID. | login_hint=someuserid |
| acr_values | 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.ex. 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. | acr_values=1 2 |
Example 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 authorization 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 authorization 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 authorization 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.