This guide will walk the developer through the steps to enable standards-based Single Sign-On (SSO) to an application by integrating the application with the Ping platform.
Using the concept of "Integrate, Federate and Operate" we can describe the steps an application owner must complete to provide and manage federated SSO in their application:
This guide will focus on the "Integrate" step.
At a high level, there are four items that we will focus on in this guide for the integration stage:
There are a number of additional considerations that should also be taken into account (for example federated user provisioning) however, this guide will focus on the SSO activity.
Knowing that to provide SSO to my customers, employees and partners I need to integrate my application into the federation infrastructure; the first question that is asked is "How do I integrate my application?". There are a number of mechanisms that can be used for this "last-mile" integrate, so to plan for application integration a number of components should be considered:
Application Format - The format of the application. Whether it is a web application, a mobile application or an API or web service.
Application Platform - The application platform can help determine the simplest integration method. The platform includes the language and framework the application is written in (i.e. Java / Spring or .NET 4.5) as well as the web application server the application is hosted on (i.e. Apache or IIS).
Application Deployment Model - Whether the application is cloud-hosted or deployed inside the firewall can also help determine the simplest integration method. For example PingOne provides a simple REST interface to enable SSO into a cloud-hosted application whereas PingFederate is a a software component but enables more options for complex integrations.
API Requirements - If the application needs to talk to specific API's it may be simpler to define the authentication mechanism around those services (i.e. if the application requires user authentication and accesses OAuth 2.0 protected REST web services, then OpenID Connect protocol is a good choice).
Availability of Source Code - There may be applications where the source code is not available (i.e. COTS application) or that the source code is not supported. Perhaps a mechanism that doesn't require code changes is the most appropriate.
With the information gathered in the previous stage, we can narrow down our integration options to determine if we need to make code changes to support the integration. The next sections will detail the specifics for integrating the different application formats, however the following general steps should be considered for all application formats before opening up the code in the application:
Our first scenario involves analyzing a web application to determine the changes required to make the application behave in a federated model. We will first identify what a typical web application looks like and how it will look after it has been integrated. Then we will use the information we gained in the previous section and walk through the process needed to integrate a web application.
A user via their web browser access the application, when they visit a protected page the application wil prompt them for authentication. In a non-federated model this is typically an application login form where the user enters their username and password. The application will then validate these credentials against the user authentication store (an internal data store or maybe a networked directory). If the credentials are valid and the authenticated user is authorized to access the protected content, the user is provided an authenticated session and is allowed to continue.
The goal of application integration for a web application is to move the authenication flow to a federated browser SSO model. As we know with the browser SSO model, the authentication event is offloaded to the identity provider and replaced with a mechanism to validate the authentication token returned via the authentication process. When a user accesses protected content, the application will redirect the users browser to the federated sign-in process. The user authenticates at the identity provider, a security token is issued and provided to the service provider who creates a session in the application.
As we learned in the previous section, there are four items we will evaluate:
The sign-on process may contain more than one location where a visitor can authenticate; the "front door", at an approval stage, if there are any APIs exposed by the application etc. It is important to identify the events in the application that require authentication and what authentication requirements each event has (ie an approval process may require a step-up to a stronger form of authentication such as a second factor).
Focusing on the "front-door" authentication, a general web application sign-on process will go through a simple workflow:
To change this workflow to support a federated authentication model, when an unauthenticated user appears the application will redirect the users browser to the SSO process. This will result in the user being challenged for authentication at the identity provider and (after a successful authentication) a token returned to the application sign-on process.
The sign-in process is now expecting three user states:
The results of the authentication request are a token containing proof of authentication and the additional attributes required by the application. The application can use these attributes to create the application session and personalize the application for the user.
More than likely, an application requires more information about the user during authentication (i.e. a list of groups to use for authorization decisions or the user's preferred language to personalize the application) these additional attributes can be provided by the authentication provider during the authentication event or through an out-of-band process (i.e. federated provisioning (SCIM) or via an API call like the OpenID Connect UserInfo API).
An application may have an application data store that contains application-specific information about the incoming user. For some applications the only information the application needs from the authentication provider is the username. It can then map that user to their application profile to associate the user with their application profile and authorizations.
Once we have an authenticated user (and their user profile), the next event is the authorization and access control stage. The application can use the attributes defined in the user profile (whether that information was received during the authentication or was provided in an alternate method) to make authorization decisions and determine the appropriate level of access to the user.
The authentication process is generally a one-time event. So when the application receives the authentication token and signs that user in, the application will generally create an application session. Once that session expires it will send the user through the sign-in process again to reauthenticate. This process may be aligned with the authentication provider to provide a seamless session extension - if the application session is shorter than the authentication provider session, then the user will automatically be logged back into the application when the session expires. Products such as PingAccess provide session management out of the box.
Terminating the session can be achieved via single log out or by just killing the application session and redirecting the user / instructing them to close their browser. Single log-out is supported across federation protocols however can be trickly to implement due to differing authentication methods provided by authentication providers. It is best to provide options to the federation partner on how to handle the sign-out event. Generally asking the partner to supply a log-out URL during configuration would be sufficient, then the application can log the user out of the application, then redirect to the URL specified by the partner.
The following question can help narrow down the integration options available for web applications. You can learn more about the integration methods in the Explore section of this
This flowchart assumes that:
|Integrate directly with application / platform||Application supports a federated security protocol such as SAML or WS-Federation (for example Microsoft SharePoint or Microsoft .NET)
PingFederate and PingOne can be used to manage federation connection to partners.
|PingFederate Web Server Integration Kits||If the application server is IIS or Apache.|
|PingFederate Language Integration Kits (Java, .NET, PHP)||Application is either Java, .NET or PHP.
Especially if there is no direct communication between PingFederate and the application.
|PingFederate Agentless Integration Kit||Any code-based language that can make HTTP calls.
Note: This kit requires direct connectivity between the application and PingFederate.
|PingOne Application Provider Services||Application is cloud-based or there are requirements that no software or libraries are to be used.|
|Native protocol support||Application requires authentication and API authorization.
OpenID Connect can be used to authenticate a user to an application client as well as provide an OAuth 2.0 access token use to secure API requests.
Note: PingFederate can perform token translation allowing one token to be exchanged for another (i.e. a SAML assertion to be exchanged for an OAuth access token)
Integrating Mobile Applications
Mobile apps are an increasingly common format for application developers. A mobile app is generally a simple, concise rendering of an application with all the functionality packed into a small easy-to-use application available on a users phone or tablet.
This section will identify a typical mobile application architecture and walk through integrating a mobile app with the federation infrastructure.
Anatomy of a Mobile Application
The mobile app architecture generally differs from a traditional web app architecture in that the mobile app is more distributed. Where a web app is more monolithic in design with complexity suiting a larger screen format with a user present, a web app is generally a more distributed model with a simple client that performs actions against an API on behalf of a user - whether the user may or may not be present.
A mobile application requires a new model of managing authentication and security due to the app architecture and fundamental differences between it and a traditional web app:
Device capabilities and restrictions also factor into an app design, specifically around security:
Although a different architecture, the same fundamental challenges remain: to eliminate passwords and reduce the authentication complexity from the app developer.
As the mobile app architecture generally involves both the app client and a resource or API that the app is communicating with, mobile app security involves securing both sides. Authentication to the app client (for user identification, personalisation, access to stored data etc) and securing of the API calls to the backend services.
Like web application SSO, eliminating passwords and replacing with a standards-based security token the application developer can offload the authentication complexity from the application to the authentication provider. The results are a flexible token model that the application can use to be assured of the identity of the user authenticating and can use to authorize access to backend APIs (without storing or transferring passwords).
Authentication to mobile applications is also greatly affected by user experience requirements. Better application user experience may be to authenticate a user natively in the application or via a web view in the application, however would limit the authentication flexibility provided when the user is redirected to the mobile browser for authentication (additional authentication functionality such as certificate authentication and a reusable authentication provider session to facilitate SSO across applications).
The prevailing standards for securing mobile applications are OpenID Connect and OAuth 2.0. These complementary protocols allow and application to authenticate a user, retrieve profile information about that user and identify that user to APIs that it calls on the users behalf.
In the OpenID Connect / OAuth 2.0 flow, a mobile app (client) will redirect the user to the Authorization Server for authentication the result of this will be two tokens returned to the client app, an id_token containing information about the user’s authentication event and an
access_token which the client can use as authorization to protected APIs.
The client will then validate those tokens and, if valid, consider the user authenticated. If additional profile information is required, the client can call the UserInfo endpoint on the AS to retrieve additional information about the authenticated user.
Authentication and Single Sign-on
To leverage OpenID Connect for authentication to a mobile application, the app will need to implement a few simple items:
There are a number of OAuth 2.0 and OpenID Connect libraries and frameworks available via open source which can simplify the implementation even further.
OpenID Connect and OAuth 2.0 can provide secure single sign-on to your mobile applications and the APIs that those applications rely on. By removing passwords from the equation, apps are more secure. By reducing the authentication complexity, developers can focus on building the application rather than the authentication model.
User experience requirements may dictate that the user remain in the application and not redirected to a web flow. In this case, the OAuth 2.0 Resource Owner Password Credentials flows can be used to exchange the user's username / password for OAuth access tokens. As the flow requires a username and password for authentication, this limits the opportunity to handle federated partners.
OpenID Connect publishes an endpoint on the authorization server called the UserInfo endpoint. An application can make a REST call to this endpoint authenticating with the OAuth 2.0 access token assigned to the user. This call will return the user's profile information.
Authorization and Access Control
Generally authorization for native mobile apps is enforced at the back-end API. After a user authenticates, the application will call a back-end API with the OAuth 2.0 access token. If the token has expired, is not valid or the authorizations provided in the access token are not sufficient for the request, then the API call will fail. The application should handle these failures gracefully.
The application itself may also enforce access control based on the attributes returned in the user profile. For example and enterprise application may only be available for user's in the finance department. If an enterprise user from marketing launches the mobile app, they may be denied access because of their user profile attributes.
A mobile application doesn't have a session as we expect from a web application. Typically the application session is managed by the lifetime of the OAuth 2.0 access token. While the token is valid the user can make API requests and interact with the application. When the access token expires the API calls will fail and the user will need to retrieve a new token to make the API calls.
OAuth 2.0 includes a concept of refresh tokens that can be exchanged for a new access token without requiring the end user to re-authenticate. This can be useful for "offline access" scenarios where the application may want to make a call while the user is not present in the application (i.e. check an order status while the application is running in the background). If a user loses their device, then these refresh tokens should be invalidated so that the application is not available to unauthorized users.
Selecting an Integration Method for Mobile Apps
Mobile application integration is fairly straightforward with the OAuth 2.0 and OpenID Connect 1.0 protocols. Achieving single sign-on across applications has proven to be the challenging piece.
For more information about leveraging the mobile OS to facilitate single sign-on, refer to the Native Application SSO (NAPPS) Developers Guide.
Integrating APIs and Web Services
APIs and Web Services are the heart of applications and system development. They enable us to re-use tried and trusted code across multiple applications and application formats and providing access for partners into internal systems.
APIs and web services are now a common method of accessing and exposing an application's functionality and therefore a critical interface to secure.
Anatomy of APIs and Web Services
APIs and Web Services can take the form of SOAP-based or REST-based services:
Selecting an Integration Method for APIs and Web Services
As we learned with web and mobile applications, federating API and web services security can greatly increase the flexibility of the APIs and services. By federating, you are replacing username/passwords with tokens allowing an external authentication system to handle the authentication complexity. This in turn allows APIs and services to use that token to authorise access to resources rather than manage the authentication process themselves.
REST-based web services and APIs can leverage OAuth 2.0 for API protection. In the OAuth 2.0 terminology, the API will act as the Resource Server (RS). As a request is made to the API, an OAuth access_token will be presented as a bearer token in the "authorization" HTTP header. The API will validate this token and use the attributes provided in the token to authorize access to the API.
SOAP services protected by WS-Security / WS-Trust standards leverage a Security Token Service (STS) to broker the federation transaction. The STS can exchange WS-Security tokens for federated security tokens (i.e. a SAML assertion) to provide cross-domain, federated access to your web services.