Skip to content

Latest commit

 

History

History
106 lines (69 loc) · 7.8 KB

general_view.adoc

File metadata and controls

106 lines (69 loc) · 7.8 KB
Raw

Authentication procedures

Authentication Flows

In order to interact with this service, it is necessary to implement one of the three authorization flows defined by OpenID Connect 1.0 standard: implicit flow, authorization code flow and hybrid flow.

  • Implicit flow. This method is recommended for browser-based apps. Its main steps are:

    1. A request is made to the Authorization Endpoint. The Authorization Server will redirect the user to the sign-in page.

    2. The end-user will then authenticate with a set of required credentials.

    3. The Authorization Server will answer back with a redirection URI and an Access Token.

    4. The Access Token can be used to request information about the end-user via the User Info Endpoint.

  • Authorization Code flow. This method is recommended for apps running on a web server or native mobile applications. Its main steps are:

    1. A request is made to the Authorization Endpoint. The Authorization Server service will redirect the user to the sign-in page.

    2. The end-user will then authenticate with a set of credentials required.

    3. The Authorization Server will answer back with an authorization code.

    4. The Client can now use the received code to request an Access Token through the Token Endpoint.

    5. Once the client application has acquired an Access Token, it will be possible to request information about the end-user via the User Info Endpoint.

  • Hybrid Code flow. This method merges characteristic from both of the previously mentioned methods. Currently, the usage of this method is not recommended with the Authorization Server.

To implement any of the flows, it is necessary to specify the response type on the request to the Authorization Server. OpenID Connect specification indicates the combination of response types necessary to implement each flow:

oidc response types
Figure 1. Response Types on OpenID Connect

Client authentication

When accessing the Token Endpoint, clients using the implicit flow are not required to be authenticated, but if the client uses the Authorization Code Flow, it must provide its credentials.

These credentials will be provided by NextGEOSS UM: client_id and client_secret.

Request Endpoints for Authentication

All endpoints require a set of mandatory parameters in order to generate a valid response. Their URLs can be obtained by means of a Discovery URI that answers back with a set of endpoints and their URLs. All these URLs must be accessed by means of a GET request, and require a set of mandatory parameters:

  • Discovery URI: /.well-known/openid-configuration

  • Authorization Endpoint (GET): /oxauth/restv1/authorize Parameters:

    • scope: The request should include an array of scopes, with one of them being “openid”.

    • response_type: Its value should be desired combination according to the OpenID Connect response type table.

    • client_id: Provided by NextGEOSS UM.

    • redirect_uri: It should point to the client application and match the URI given on the acceptance request.

    • state (optional): Opaque value used to maintain state between the request and the callback. Typically, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie.

    • nonce (optional/required for Implicit Flow): String value used to associate a Client session with an ID Token, and to mitigate replay attacks (it can have ANY value)

Example:
GET oxauth/restv1/authorize?scope=openid&client_id=@!5C7F.E36B.5DE3.15EE!0001!6B53.87B4!0008!A121.D32B.8BCD.4E14&redirect_uri=app://test&response_type=code

If the application is trying to authenticate without user input, user credentials must be provided through the Authorization header. The code will be encoded as a parameter in the Location response header.

  • Token Endpoint (POST): /oxauth/restv1/token

    • grant_type: implicit / authorization_code (depending on the authorization flow).

    • Code*: Used only with grant_type=authorization_code

    • redirect_uri: It should point to the client application and match the URI given on the acceptance request.

    • scope: The request should include an array of scopes, with one of them being “openid”.

    • client_id*: Provided by NextGEOSS UM, only necessary with grant_type=authorization_code.

    • client_secret*: Provided by NextGEOSS UM, only necessary with grant_type=authorization_code

Authorization procedures

Authentication

When performing an access request, there might be a requirement to authenticate prior to the execution of the Resource Access Flow. This authentication will ensure that the Authorization Server is aware of all relevant End-User claims that may be necessary to grant or deny access to a resource.

The authentication flows explained on prior sections of this guide serve as a guideline for this step. It is important to note that any given client that aims at performing a UMA based access request should locally store the identity token (id_token field) generated during authentication.

"Naive" Access Request

As an initial step to the Access Request, the Client Application must access the UMA-protected Resource Server in a non-secured manner. If the service is correctly protected with UMA, the response will be a 401 Unauthorized HTTP response with a Response Header presenting the following structure:

WWW-Authenticate: UMA realm="nextgeoss",as_uri="https://um.nextgeoss.eu",ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de"

The client must store the value assigned to the ticket field, which references the resource being accessed.

Generation of a Resource Access Token (RPT)

When acquiring a resource token, the UMA service will try to check user claims (such as attributes, user ID, client ID). Some of those claims can’t be gathered using the service itself and the parameters on the request, so it might be necessary to gather those claims and get a new ticket. If an id_token has previosuly being issued, it can be passed as part of the request to inform the NextGEOSS UM Platform of the End-User claims relevant for authorization.

  • Token Endpoint (POST): /oxauth/restv1/token

    • scope=<scopes> (separated by a space)

    • client_secret=<secret>

    • ticket=<ticket>

    • client_id=<client_id>

    • grant_type=urn:ietf:params:oauth:grant-type:uma-ticket

    • claim_token=<id_token>

    • claim_token_format=http%3A%2F%2Fopenid.net%2Fspecs%2Fopenid-connect-core-1_0.html%23IDToken

If the ticket is valid, a Resource Token a JSON response with the field “access_token” will be issued. If not, a 403 (Forbidden) response will be issued. This response can have another JSON attached explaining the error. If the error matches the “need_info” string, it is possible to extract an URL from the field “redirect_user” to gather claims.

  • GET <redirect_user_URI>?ticket=<ticket>&client_id=<client_id>&claims_redirect_uri=<redirect_uri>

The redirect_uri in this request must be specified on the client configuration. This request will result will redirect the user to another location with the response parameters parsed in the URL. One of this parameters should be a new “ticket” that can be used to request the token again, taking into account the gathered claims.

In any case, with or without claims, the token endpoint can issue a 403 Forbidden response indicating that the policies in place forbid access to the resource.

Access Request with a Resource Access Token (RPT)

Once the RPT ("access_token") has been issued, the Client can perform the request on step 1 of this procedure adding the RPT in an Authorization header. The result of this request can either be a nominal answer by the Resource Server or, if the RPT is invalid or it has expired, a 401 Unauthorized response with a ticket. In that case the Client can choose to start the process from the first step.

  • Authorization: Bearer <access_token>