About SAML & OpenID Connect
In Access Manager, the identity providers that are based on SAML 2.0 and OpenID Connect protocols are supported.
SAML
SAML 2.0 (Security Assertion Markup Language 2.0) is an authentication protocol that works by exchanging XML documents between the authentication server and the application. It was designed to work on top of the Web. XML signatures and encryption are used to verify requests and responses.
There are two use cases that require the use of SAML:
- An application asks the Platform server to authenticate a user. After the user successfully logs in, the application receives an XML document that contains a SAML assertion specifying various attributes related to the user. The XML document is digitally signed by the realm and contains the access information (such as the user role mappings). The application uses the access information to determine the resources that the user is allowed to access in the application.
- A client wants to gain access to the remote services. In this case, the client asks Access Manager to send a SAML assertion to use it to invoke other remote services on behalf of the user.
SAML defines several ways to exchange XML documents when executing the authentication protocol. The following binding types are supported by the Platform.
The HTTP Redirect binding uses a series of browser redirect URIs to exchange information. The following is a brief explanation of how this binding works.
- The user visits the application, and the application determines that the user is not authenticated. The application generates an XML authentication request document and encodes it as a query parameter in a URI that is used to redirect to the Platform server. Depending on your settings, the application may also digitally sign this XML document and add this signature as a query parameter in the redirect URI to the Platform. This signature is used to validate the client that sent this request.
- The browser is redirected to the Platform. The server extracts the XML authentication request document and verifies the digital signature, if required. Then, the user has to provide the credentials to be authenticated.
- After authentication, the server generates an XML authentication response document. This document contains an SAML assertion that holds metadata about the user, such as the user's name, address, email, and any role mappings. This document is almost always digitally signed by using XML signatures and can also be encrypted.
- Then, the XML authentication response document is encoded as a query parameter in a redirect URI that brings the browser back to the application. The digital signature is also included as a query parameter. The application receives the redirect URI, extracts the XML document, and verifies the realm’s signature to ensure that the authentication response is valid. Then, the information included in the SAML assertion is used to make access decisions or display user data.
The HTTP Redirect binding is used for the browser-based applications.
The HTTP POST binding works almost the same way as the HTTP Redirect binding, but instead of GET requests, XML documents are exchanged by POST requests. The HTTP POST binding applies to browser-based applications.
ECP (Enhanced Client or Proxy) is a SAML 2.0 profile that is used for exchanging SAML attributes outside the context of a web browser. The ECP binding is mostly used for REST or SOAP-based clients.
OpenID Connect
OpenID Connect is a fully-developed authentication and authorization protocol that is an extension of the OAuth 2.0 authorization framework. OpenID Connect was designed to work with the Web. It is perfectly suited for HTML5/JavaScript applications and is easy to implement on the client side. OpenID Connect uses the JSON Web Token (JWT) set of standards that define ways to digitally sign and encrypt data in a compact and web-friendly way.
There are two use cases that require the use of OpenID Connect:
- An application asks the Platform server to authenticate a user. After the user successfully logs in, the application receives an identity token and an access token. The identity token contains information about the user (such as the username, email, and other profile information). The access token is digitally signed and contains access information (such as the user role mappings). The application uses the access information to determine the resources that the user is allowed to access in the application.
- A client wants to gain access to remote services. In this case, the client asks the Platform to obtain an access token. The client can use the access token to invoke other remote services on behalf of the user. The Platform authenticates the user and then asks the user for consent to grant access to the client that requests access. Then, the client receives the access token, which is digitally signed. The client can make REST invocations on remote services by using this access token. The REST service extracts the access token and verifies the token signature. Then, based on the access information within the token, the REST service decides whether to process the request.
OpenID Connect has different ways for a client or application to authenticate a user and receive an identity and access token. Which path you use depends greatly on the type of application or client requesting access. The following are the descriptions of the flows supported in Access Manager.
This is a browser-based protocol. We recommend using it to authenticate and authorize browser-based applications. With the authorization code flow, browser redirects are used to obtain an identity token and an access token.
A browser visits an application. The application notices that the user is not logged in and redirects the browser to Access Manager to be authenticated. The application passes along a callback URL (a redirect URL) as a query parameter in this browser redirect that Access Manager will use when it finishes authentication.
Access Manager authenticates the user and creates a one-time, very short lived, temporary code. Access Manager redirects back to the application by using the callback URL provided earlier. In addition, the temporary code is added as a query parameter in the callback URL.
The application extracts the temporary code and makes a background out of band REST invocation to Access Manager to exchange the code for an identity, access, and refresh token. After this temporary code has been used once to obtain the tokens, it can never be used again. This prevents potential replay attacks.
It is important to note that access tokens are usually short-lived and often expire after several minutes. The additional refresh token that is transmitted by the login protocol allows the application to obtain a new access token after it expires. This refresh protocol is important in the situation of a compromised system. If access tokens are short-lived, the whole system is only vulnerable to a stolen token for the lifetime of the access token. Future refresh token requests will fail if an admin has revoked access. This makes things more secure and more scalable.
Another important aspect of this flow is the concept of a public versus a confidential client. Confidential clients are required to provide a client secret when they exchange the temporary codes for tokens. Public clients are not required to provide this client secret. Public clients are perfectly fine so long as HTTPS is strictly enforced and you are very strict about what redirect URIs are registered for the client. HTML5/JavaScript clients always have to be public clients because there is no way to transmit the client secret to them in a secure manner. Again, this is fine so long as you use HTTPS and strictly enforce redirect URI registration.
This is a browser-based protocol that is similar to the authorization code flow. The difference is that there are fewer requests and no refresh tokens involved. The drawback of this flow is the possibility of access tokens being leaked in the browser history because tokens are transmitted via redirect URIs. In addition, this flow does not provide the client with a refresh token, which means the access tokens should either be long-lived or users should reauthenticate when the tokens expire.
- A browser visits an application. The application notices that the user is not logged in, so it redirects the browser to Access Manager to be authenticated. The application passes along a callback URL (a redirect URL) as a query parameter in this browser redirect that Access Manager will use when it finishes authentication.
- Access Manager authenticates the user and creates an identity and access token. Access Manager redirects back to the application by using the callback URL provided earlier. In addition, the identity and access tokens are added as query parameters in the callback URL.
- The application extracts the identity and access tokens from the callback URL.
The following is a list of the OpenID Connect endpoints that Access Manager publishes.
The root of the URL is the HTTP(S) protocol, hostname, and usually the path prefixed with '/auth' (for example, https://localhost:8080/auth).
Endpoint | Description |
---|---|
/realms/{realm-name}/protocol/openid-connect/token | This is the URL endpoint for obtaining a temporary code in the Authorization Code Flow or for obtaining tokens via the Implicit Flow, Direct Grants, or Client Grants. |
/realms/{realm-name}/protocol/openid-connect/auth | This is the URL endpoint for the Authorization Code Flow to turn a temporary code into a token. |
/realms/{realm-name}/protocol/openid-connect/logout | This is the URL endpoint for performing the logouts. |
/realms/{realm-name}/protocol/openid-connect/userinfo | This is the URL endpoint for the User Info service described in the OIDC specification. |
In all of these, replace {realm-name} with the name of the realm.
Comments
0 comments