Introduction
This guide describes how to develop OpenID Connect applications for use with Cloud Access Manager.
Topics:
What is OAuth v2.0?
OAuth v2.0 is a standard for securely granting access to a web resource. With OAuth v2.0, an application (the client) can ask a service (the authorization server) for permission to access a private resource hosted on a resource server, and owned by an end-user (the resource owner). To grant permission to access the resource, the authorization server must authenticate the resource owner and obtain his consent.
The specification for OAuth v2.0 is available to view online at https://tools.ietf.org/html/rfc6749 which contains this example:
An end-user (resource owner) can grant a printing service (client) access to her protected photos stored at a photo-sharing service (resource server), without sharing her username and password with the printing service. Instead, she authenticates directly with a server trusted by the photo-sharing service (authorization server), which issues the printing service delegation-specific credentials (access token).
OAuth v2.0 is often loosely regarded as an authentication protocol in its own right; however the specification does not prescribe the means by which credentials are collected from the end-user.
Figure 1: Conceptual overview of OAuth v2.0
OAuth v2.0 flows
OAuth v2.0 presents four different flows which are appropriate to different scenarios:
Cloud Access Manager provides the Authorization Server function for Authorization Code Flow and Implicit Flow. It does not support Resource Owner Password Credentials Flow or Client Credentials Flow.
Authorization Code Flow
This is the best choice for web applications which run on a web server, because they can be reliably authenticated. This flow requires a browser, because it relies on HTTP redirects, but the browser can be embedded into the client application. The client invokes the browser, directing it to the authorization server in order to authenticate the user and obtain consent (in the form of an authorization code). With this authorization code, the client app can contact the authorization server directly (not through the browser) in order to obtain an access token, which can then be used to access the required resource.
Figure 2: Authorization Code Flow
-
The client initiates the flow by directing the user's browser to the authorization endpoint, adding querystrings to the URI as follows:
Table 1: Authorization Code Flow querystrings Querystring Description response_type: Set to “code” to request that the Authorization Server initiate an Authorization Code flow. Client_id: A unique identifier generated by Cloud Access Manager for the client when the application definition is configured. redirect_uri: The URI which Cloud Access Manager will redirect the user’s browser to, when authorization processing is complete. scope (optional): Used to determine what resources are being requested from the Resource Server. state (optional): A value which the client can use to maintain state between request and callback. This can be used to prevent cross-site request forgery. - Cloud Access Manager authenticates the user (using the browser) and establishes whether the user grants or denies the client's access request.
- Assuming the user grants access, Cloud Access Manager redirects the browser back to the client using the redirection URI provided earlier. The redirection URI includes an authorization code and any local state provided by the client.
- The client requests an access token from Cloud Access Manager's token endpoint by including the authorization code received in the previous step. When making the request, if it is a confidential client (see below) the client authenticates with Cloud Access Manager using HTTP basic authentication (with the Client ID as the username and the Shared Secret as the password). The client includes the redirection URI used to obtain the authorization code for verification.
- Cloud Access Manager authenticates the client, validates the authorization code, and ensures that the redirection URI received matches the URI used to redirect the client in step 3. If valid, Cloud Access Manager responds with an access token. The access token can then be used to access the required resource.