Overview of SAML

OneLogin has implemented and open-sourced SAML toolkits for five web development platforms:

•   PHP
•   Python
•   Ruby
•   Java
•   .NET

Security Assertion Markup Language (SAML) is a standard for logging users into applications based on their sessions in another context. This single sign-on (SSO) login standard has significant advantages over logging in using a username/password:

• No need to type in credentials
• No need to remember and renew passwords
• No weak passwords

Most organizations already know the identity of users because they are logged in to their Active Directory domain or intranet. It makes sense to use this information to log users in to other applications, such as web-based applications, and one of the more elegant ways of doing this is by using SAML.

SAML is very powerful and flexible, but the specification can be quite a handful. OneLogin’s open-source SAML toolkits can help you integrate SAML in hours, instead of months. We’ve come up with a simple setup that will work for most applications.

How SAML Works

SAML SSO works by transferring the user’s identity from one place (the identity provider) to another (the service provider). This is done through an exchange of digitally signed XML documents.

Consider the following scenario: A user is logged into a system that acts as an identity provider. The user wants to log in to a remote application, such as a support or accounting application (the service provider). The following happens:

1. The user accesses the remote application using a link on an intranet, a bookmark, or similar and the application loads.
2. The application identifies the user’s origin (by application subdomain, user IP address, or similar) and redirects the user back to the identity provider, asking for authentication. This is the authentication request.
3. The user either has an existing active browser session with the identity provider or establishes one by logging into the identity provider.
4. The identity provider builds the authentication response in the form of an XML-document containing the user’s username or email address, signs it using an X.509 certificate, and posts this information to the service provider.
5. The service provider, which already knows the identity provider and has a certificate fingerprint, retrieves the authentication response and validates it using the certificate fingerprint.
6. The identity of the user is established and the user is provided with app access.

SAML SSO Flow

The diagram below illustrates the single sign-on flow for service provider-initiated SSO, i.e. when an application triggers SSO.

Identity provider-initiated SSO is similar and consists of only the bottom half of the flow.

Dev Overview of OpenID Connect

OpenID Connect is a simple identity layer built on top of the OAuth 2.0 protocol, which allows clients to verify the identity of an end user based on the authentication performed by an authorization server or identity provider (IdP), as well as to obtain basic profile information about the end user in an interoperable and REST-like manner. OpenID Connect specifies a RESTful HTTP API, using JSON as a data format. 

OpenID Connect is an increasingly common authentication protocol: when an app prompts you to authenticate using your Facebook or Google+ credentials, the app is probably using OpenID Connect.

OpenID Connect allows a range of clients, including web-based, mobile, and JavaScript clients, to request and receive information about authenticated sessions and end-users.

OneLogin provides a custom connector option that makes it easy to configure your OpenID Connect-enabled app to use OneLogin as the Identity Provider (IdP) in an OpenID Connect flow.

For more information about API authorization, see How to setup an API Authorization PoC.

Why Adopt OpenID Connect for my App?

OpenID Connect is easier to integrate than SAML, and it can work with a wider variety of apps. Specifically, it provides:

• Easily consumed identity tokensClient apps receive the user’s identity encoded in a secure JSON Web Token (JWT) called the ID token. JWTs are elegant and portable and support a range of signature and encryption algorithms.
• The OAuth 2.0 protocolClients use OAuth 2.0 flows to obtain ID tokens, which work with web apps as well as native mobile apps. OAuth 2.0 also means that you have a single protocol for authentication and authorization (obtaining access tokens).
• Simplicity with capabilityOpenID Connect is simple enough to integrate with basic apps, while also offering features and security options that can meet demanding enterprise requirements.

Grant Types

OpenID Connect supports the following authentication flows:

• The Implicit Flow is required for apps that have no “back end” logic on the web server, like a Javascript app.
• The Authentication (or Basic) Flow is designed for apps that have a back end that can communicate with the IdP away from prying eyes.
• The Resource Owner Password Grant does not have an login UI and is useful when access to a web browser is not possible.
• The Client Credentials Grant is useful for machine to machine authorization.

Implicit Flow

The Implicit flow is required for apps and websites that have no back end logic on the web server, and everything that is passed between the app or site and the IdP can be viewed using browser development tools.

In the Implicit flow, a public/private key (JSON Web Key or JWK) scheme is used to encrypt or sign user details. When you register your client app with the IdP (OneLogin), you will receive a client ID and a client secret. In an Implicit flow, the client secret should never be exposed.

In Step 1, the user attempts to start a session with your client app and is redirected to the OpenID Provider (OneLogin), passing in the client ID, which is unique for that application. In Step 2, the OpenID Provider authenticates and authorizes the user for a particular application instance. In Step 3, user details are encoded by the OpenID Provider into an id_token (JWT) that contains user information (scopes, in OAuth terms) and signature (using RS256), which is passed to a preconfigured Redirect page on the web server. In Step 4, the client app confirms the JWT id_token and confirms the signature using the public key. If everything is fine, a session is established for the user.

In the Implicit flow, the transaction is secure despite the fact that everything is passed in the “front end” and the client app cannot be authenticated, because the IdP sends tokens encrypted using a public/private key scheme and will only send tokens to the preconfigured Redirect URI. In other words, someone could steal the public key and client id, but that doesn’t matter, because only the IdP has the proper information (the redirect URI for the intended client app and the private key) to use the public key and client ID correctly.

Authentication Flow

The Authentication (or Basic) flow is an option for apps that have web-server logic that enables back-end communication with the IdP (OneLogin). It functions like a traditional three-legged OAuth flow and results in a traditional OAuth access token being returned in secret to the web application via calls made on the back end. In this flow, rather than transmit the user details, the provider sends a special, one-time-use code that can be exchanged by the back-end web service for an OAuth access token. This exchange needs to include the client id and client secret in addition to the code, just like a traditional OAuth 2.0 flow. It is more secure than the Implicit flow, because tokens are not visible through the browser and the client app can also be authenticated.

In Step 1, the user attempts to start a session with your client app and is redirected to the OpenID Provider (OneLogin), passing in the client ID, which is unique for that application. In Step 2, the OpenID Provider authenticates and authorizes the user for a particular application instance. So far, it looks like the Implicit flow. But in Step 3, a one-time-use code is passed back to the web server using a predefined Redirect URI. In Step 4, the web server passes the code, client ID, and client secret to the OpenID Provider’s token endpoint, and the OpenID Provider validates the code and returns a one-hour access token. In Step 5, the web server uses the access token to get further details about the user (if necessary) and establishes a session for the user.

Getting Started

To configure OneLogin as the IdP for your OpenID Connect-enabled app, you must:

1. Enable your app to use OpenID Connect.
2. Configure OneLogin and your app to talk to each other.

Postman Collection

Replace sample variables indicated by {{ }} with your actual values.

 Download for the OpenId Connect API