Identity Patterns with the WSO2 Identity Server
User administrators by the user store

Problem:
  • Define user administrators by user store. For example, a user belongs to the role foo-admin will be able to perform user admin operations on the foo user store, while he/she won’t be able to perform user admin operations on the bar user store.
Solution:
  • Deploy the WSO2 Identity Server as an identity provider over multiple user stores. 
  • Define a XACML policy, which specified who should be able to do which operation on user stores. 
  • Create a user store operation listener and talk to the XACML PDP during user admin operations. 
  • Create roles by user store and user administrators to appropriate roles. Also, make sure each user administrator has the user admin permissions from the permission tree. 
  • Products: WSO2 Identity Server 4.6.0+ 

Identity Patterns with the WSO2 Identity Server
Service provider-specific user stores

Problem:
  • The business users need to access multiple service providers supporting multiple heterogeneous identity federation protocols. 
  • When the user gets redirected to the identity provider, the users only belong to the user stores specified by the corresponding service provider, should be able to login or get an authentication assertion. 
  • In other words, each service provider should be able to specify from which user store it accepts users.
Solution:
  • Deploy the WSO2 Identity Server as an identity provider over multiple user stores and register all the service providers. 
  • Extend the pattern 18.0 Fine-grained access control for service providers to enforce user store domain requirement in the corresponding XACML policy. 
  • Use a regular expression to match allowed user store domain names with the authenticated user’s user store domain name. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Home realm discovery

Problem:
  • The business users need to login to multiple service providers via multiple identity providers. 
  • Rather than providing a multi-login option page with all the available identity provider, once redirected from the service provider, the system should find out who the identity provider corresponding to the user and directly redirect the user there.
Solution:
  • Deploy WSO2 Identity Server as an identity provider and register all the service providers and identity providers. 
  • For each identity provider, specify a home realm identifier. 
  • The service provider prior to redirecting the user to the WSO2 Identity Server must find out the home realm identifier corresponding to the user and send it as a query parameter. 
  • Looking at the home realm identifier in the request the WSO2 Identity Server redirect the user to the corresponding identity provider. 
  • In this case, there is a direct one-to-one mapping between the home realm identifier in the request and the home realm identifier value set under the identity provider configuration. This pattern can be extended by writing a custom home realm discovery connector, which knows how to relate and find the corresponding identity provider by looking at the home realm identifier in the request, without maintaining a direct one-to-one mapping. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Authenticate the users against one user store but fetch user attributes from multiple other sources

Problem:
  • User credentials are maintained in a one user store while user attributes are maintained in multiple sources. 
  • When the user logs into the system via any SSO protocol (SAML 2.0, ODIC, WS-Federation), build the response with user attributes coming from multiple sources.
Solution:
  • Mount the credential store and all the attribute stores as user stores to the WSO2 Identity Server. Follow a naming convention while naming the user stores where the attributes store can be differentiated from the credentials stores just by looking at the user store domain name. 
  • Build a custom user store manager (extending the current user store manager corresponding to the type of the primary user store), which is aware of all the attribute stores in the system and override the method, which returns user attributes. The overridden method will iterate through the attribute stores find the user’s attributes and will return back the aggregated result. 
  • Set the custom user store manager from the previous step as the user store manager corresponding to the primary user store. 
  • Products: WSO2 Identity Server 4.6.0+ 

Identity Patterns with the WSO2 Identity Server
User administration operations from a third-party web app

Problem:
  • A third party web app needs to perform all user management operations such as all CRUD operations on users and roles, user/role assignments and password recovery, without having to deal directly with underlying user stores (LDAP, AD, JDBC).
Solution:
  • Deploy the WSO2 Identity Server over the required set of user stores. 
  • The WSO2 Identity Server exposes a set of REST endpoints as well as SOAP-based services for user management, the web app just need to talk to these endpoints, without having to deal directly with underlying user stores (LDAP, AD, JDBC). 
  • Products: WSO2 Identity Server 4.0.0+ 

Identity Patterns with the WSO2 Identity Server
Fine-grained access control for SOAP services

Problem:
  • Access to the business services must be done in a fine-grained manner. 
  • Only the users belong to the business-admin role should be able to access foo and bar SOAP services during a weekday from 8 AM to 5 PM.
Solution:
  • Deploy WSO2 Identity Server as a XACML PDP (Policy Decision Point). 
  • Define XACML policies via the XACML PAP (Policy Administration Point) of the WSO2 Identity Server. 
  • Front the SOAP services with WSO2 ESB and represent each service a proxy service in the ESB. 
  • Engage the Entitlement mediator to the in-sequence of the proxy service, which needs to be protected. The Entitlement mediator will point to the WSO2 Identity Server’s XACML PDP. 
  • All the requests to the SOAP service will be intercepted by the Entitlement mediator and will talk to the WSO2 Identity Server’s XACML PDP to check whether the user is authorized to access the service. 
  • Authentication to the SOAP service should happen at the edge of the WSO2 ESB, prior to Entitlement mediator. 
  • If the request to the SOAP service brings certain attributes in the SOAP message itself, the Entitlement mediator can extract them from the SOAP message and add to the XACML request. 
  • Products: WSO2 Identity Server 4.0.0+, WSO2 ESB, Governance Registry 

Identity Patterns with the WSO2 Identity Server
Render menu items in a web app based on the logged-in user’s fine-grained permissions

Problem:
  • When a business user logs into a web app, the menu items in the web app should be rendered dynamically based on the user’s permissions. 
  • There can be a case if the same user logs at 9 AM and then again at 9 PM could see different menu items as the permission can also be time sensitive. 
  • There can be a case if the same user logs in from China and then again from Canada could see different menu items as the permission can also be location sensitive.
Solution:
  • Deploy WSO2 Identity Server as a XACML PDP (Policy Decision Point). 
  • Define XACML policies via the XACML PAP (Policy Administration Point) of the WSO2 Identity Server. 
  • When a user logs into the web app, the web app will talk to the WSO2 Identity Server’s XACML PDP endpoint with a XACML request using XACML multiple decision profile and XACML multiple resource profile. 
  • After evaluating the XACML policies against the provided request, the WSO2 Identity Server returns back the XACML response, which includes the level permissions the user has on each resource under the parent resource specified in the initial XACML request. Each menu item is represented as a resource in the XACML policy. 
  • The web app caches the decision to avoid further calls to the XACML PDP. 
  • Whenever some event happens at the XACML PDP side, which requires expiring the cache, the WSO2 Identity Server will notify a registered endpoint of the web app. 
  • Products: WSO2 Identity Server 4.0.0+ 

Identity Patterns with the WSO2 Identity Server
Single Sign On between a legacy web app, which cannot change the user interface and service providers, which support standard SSO protocols.

Problem:
  • The business users need to access a service provider,where its UI cannot be changed. The users need to provide their user credentials to the current login form of the service provider. 
  • Once the user logs into the above service provider, and then clicks on a link to another service (which follows a standard SSO protocol), the user should be automatically logged in. The vice-versa is not true.
Solution:
  • Deploy WSO2 Identity Server as the Identity Provider and register all the service providers with standard inbound authenticators (including the legacy app). 
  • For the legacy web app, which does not want to change the UI of the login form, enable basic auth request path authenticator, under the Local and Outbound Authentication configuration. 
  • Once the legacy app accepts the user credentials from its login form, post them along with the SSO request (SAML 2.0/OIDC) to the WSO2 Identity Server. 
  • The WSO2 Identity Server will validate the credentials embedded in the SSO request and if valid, will issue an SSO response and the user will be redirected back to the legacy application. The complete redirection process will be almost transparent to the user. 
  • When the same user tries to log in to another service provider, the user will be automatically authenticated, as the previous step created a web session for the logged in user, under the WSO2 Identity Server domain. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Access a microservice from a web app protected with SAML 2.0 or OIDC

Problem:
  • The business users need to access multiple service providers, supporting SAML 2.0 and OIDC-based authentication. 
  • Once the user logs into the web app, it needs to access a microservice on behalf of the logged in user.
Solution:
  • Deploy WSO2 Identity Server as the Identity Provider and register all the service providers with OIDC or SAML 2.0 as the inbound authenticator. 
  • Enable JWT-based access token generator in the WSO2 Identity Server. 
  • Develop and deploy all the microservices with WSO2 MSF4J. 
  • If the service provider supports SAML 2.0 based authentication, once the user logs into the web app, exchange the SAML token to an OAuth access token by talking to the /token endpoint of the WSO2 Identity Server, following the SAML 2.0 grant type for OAuth 2.0 profile. This access token itself is a self-contained JWT. 
  • If the service provider supports OIDC based authentication, once the user logs into the web app, exchange the ID token to an OAuth access token by talking to the /token endpoint of the WSO2 Identity Server, following the JWT grant type for OAuth 2.0 profile. This access token itself is a self-contained JWT. 
  • To access the microservice, the pass the JWT (or the access token) in the HTTP Authorization Bearer header over TLS. 
  • MSF4J will validate access token (or the JWT) and the token will be passed across all the downstream microservices. 
  • More about microservices security: https://medium.com/@prabath/securing-microservices-with-oauth-2-0-jwt-and-xacml-d03770a9a838 
  • Products: WSO2 Identity Server 5.1.0+, WSO2 MSF4J 

Identity Patterns with the WSO2 Identity Server
Enforce users to provide missing required attributes while getting JIT provisioned to the local system

Problem:
  • The business users need to access multiple service providers via federated identity provider (i.e Facebook, Yahoo, Google). 
  • Need to JIT provision all the user coming from federated identity providers with a predefined set of attributes. 
  • If any required attributes are missing in the authentication response from the federated identity provider, the system should present a UI to the user to provide those.
Solution:
  • Deploy WSO2 Identity Server as the Identity Provider and register all the service providers and federated identity providers. 
  • Enable JIT provisioning for each federated identity provider. 
  • Build a connector to validate the attributes in the authentication response and compare those against the required set of attributes. The required set of attributes can be defined via a claim dialect. If there is a mismatch between the attributes from the authentication response and the required set of attributes then this connector will redirect the user to web page (deployed under authenticationendpoints web app) to accept the missing attributes from the user. 
  • Engage the attribute checker connector from the previous step to an authentication step after the step, which includes the federated authenticator. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Accessing a SOAP service secured with WS-Trust from a web app on behalf of the logged-in user (SAML 2.0)

Problem:
  • The business users need to access multiple service providers supporting SAML 2.0 web SSO-based authentication. 
  • Once the user logs into the web app, the web app needs to access a SOAP service secured with WS-Trust on behalf of the logged in user.
Solution:
  • Deploy WSO2 Identity Server as an identity provider, and register all the service providers (with SAML 2.0 as the inbound authenticator). Further, it will also act as a Security Token Service(STS) based on WS-Trust. 
  • Deploy the SOAP service in WSO2 App Manager and secure it with WS-Security Policy to accept a SAML token as a supporting token. 
  • Deploy the web app in the WSO2 App Manager. 
  • Write a filter and deploy it in the WSO2 App Server, which will accept a SAML token coming from Web SSO flow and build a SOAP message embedding that SAML token. 
  • Since we are using SAML bearer tokens here, all the communication channels that carry the SAML tokens must be over TLS. 
  • Once the web app gets the SAML token, it will build a SOAP message with the security headers out of it (embedding the SAML token inside ActAs element of the RST) and talk to the WSO2 Identity Server’s STS endpoint to get a new SAML token to act-as the logged in user, when talking to the secured SOAP service. 
  • WSO2 App Server will validate the security of the SOAP message. It has to trust the WSO2 Identity Server, who is the token issuer. 
  • Products: WSO2 Identity Server 3.0.0+, WSO2 Application Server 

Identity Patterns with the WSO2 Identity Server
Self-signup during the authentication flow with service provider specific claim dialects

Problem:
  • The business users need to access multiple service providers supporting multiple heterogeneous identity federation protocols. 
  • When the user gets redirected to the identity provider for authentication, the identity provider should provide a page with the login options and also an option to sign up. 
  • If the user picks the sign-up option, the required set of fields for the user registration must be specific to the service provider who redirected the user to the identity provider. 
  • Upon user registration, the user must be in the locked status, and confirmation mail has to be sent to the user’s registered email address. 
  • Upon email confirmation, the user should be prompted for authentication again and should be redirected back to the initial service provider.
Solution:
  • Deploy WSO2 Identity Server as the Identity Provider and register all the service providers. 
  • Customize the login web app (authenticationendpoints) deployed inside WSO2 Identity Server to give an option user signup in addition to the login options. 
  • Follow a convention and define a claim dialect for each service provider, with the required set of user attributes it needs during the registration. The service provider name can be used as the dialect name as the convention. 
  • Build a custom /signup API, which retrieves required attributes for user registration, by passing the service provider name. 
  • Upon registration, the /signup API will use email confirmation feature in the WSO2 Identity Server to send the confirmation mail and in addition to that the /signup API also maintain the login status of the user, so upon email confirmation user can be redirected back to the initial service provider. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Fine-grained access control for service providers

Problem:
  • The business users need to access multiple service providers supporting multiple heterogeneous identity federation protocols. 
  • Each service provider needs to define an authorization policy at the identity provider, to decide whether a given user is eligible to log into the corresponding service provider. 
  • For example, one service provider may have a requirement that only the admin users will be able to login into the system after 6 PM. 
  • Another service provider may have a requirement that only the users from North America should be able to login into the system.
Solution:
  • Deploy WSO2 Identity Server as the Identity Provider and register all the service providers. 
  • Build a connector, which connects to the WSO2 Identity Server’s XACML engine to perform authorization. 
  • For each service provider, that needs to enforce access control during the login flow, engage the XACML connector to the 2nd authentication step, under the Local and Outbound Authentication configuration. 
  • Each service provider, that needs to enforce access control during the login flow, creates its own XACML policies in the WSO2 Identity Server PAP (Policy Administration Point). 
  • To optimize the XACML policy evaluation, follow a convention to define a target element under each XACML policy, that can uniquely identify the corresponding service provider. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Single Page Application (SPA) proxy

Problem:
  • Authenticate users to a single page application in a secure manner, via OAuth 2.0. 
  • The SPA accessing an OAuth-secured API, the access token must be made invisible to the end-user. 
  • The SPA accessing an OAuth-secured API, the client (or the SPA) must be authenticated in a legitimate manner.
Solution:
  • There are multiple ways to secure an SPA and this presentation covers some options: http://www.slideshare.net/prabathsiriwardena/securing-singlepage-applications-with-oauth-20 
  • This explains the SPA proxy pattern, where a proxy is introduced, and the calls from the SPA will be routed through the proxy. 
  • Build an SPA proxy and deploy it in WSO2 Identity Server. A sample proxy app is available at https://github.com/facilelogin/aratuwa/tree/master/oauth2.0-apps. 
  • The SPA proxy must be registered in the WSO2 Identity Server as a service provider, having OAuth inbound authenticator. 
  • To make the SPA proxy stateless, the access_token and the id_token obtained from the WSO2 Identity Server (after the OAuth flow) are encrypted and set as a cookie. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Mobile identity provider proxy

Problem:
  • A company builds a set of native mobile apps and deployed into company owned set of devices, which are handed over to its employees. 
  • When a user logs into one native mobile app, he/she should automatically log into all the other native apps, without further requests to provide his/her credentials. 
  • No system browser in the device.
Solution:
  • Build a native mobile app, which is the identity provider (IdP) proxy and deploy it in each device along with all the other native apps. 
  • This IdP proxy must be registered with the WSO2 Identity Server, as a service provider, having OAuth 2.0 as the inbound authenticator. 
  • Under the IdP proxy service provider configuration in WSO2 Identity Server, make sure to enable only the resource owner password grant type. 
  • Each of the native app must be registered with the WSO2 Identity Server as a service provider, having OAuth 2.0 as the inbound authenticator and make sure only the implicit grant type is enabled. 
  • Under the native app service provider configuration in WSO2 Identity Server, make sure to have oauth-bearer as a request-path authenticator, configured under Local and Outbound Authentication configuration. 
  • The IdP proxy app has to provide a native API for all the other native apps. 
  • When a user wants to login into an app, the app has to talk to the login API of the IdP proxy app passing its OAuth 2.0 client_id. 
  • The IdP proxy app should first check whether it has a master access token, if not it should prompt the user to enter username/password and then using the password grant type talk to the WSO2 Identity Server’s /token API to get the master access token. The IdP proxy must securely store the master access token — and it’s per user. If the master access token is already there, the user needs to not to authenticate again. 
  • Now, using the master access token (as the Authorization Bearer header), the IdP proxy app should talk (HTTP POST) to the /authorize endpoint of the WSO2 Identity Server, following the implicit grant type with the client_id provided by the native app. Also, use openid as the scope. 
  • Once the access token and the ID token are returned from the WSO2 Identity Server, the IdP proxy will return them back to the native app, who did the login API call first. 
  • Products: WSO2 Identity Server 5.2.0+ 

Identity Patterns with the WSO2 Identity Server
Federation Proxy

Problem:
  • All the inbound requests for all the service providers inside the corporate domain must be intercepted centrally and enforce authentication via an Identity Hub. 
  • Users can authenticate to the hub, via different identity providers. 
  • All the users, who authenticate via the hub must be provisioned locally. 
  • One user can have multiple accounts with multiple identity providers connected to the hub and when provisioned into the local system, the user should be given the option to map or link all his/her accounts and then pick under which account he/she needs to login into the service provider.
Solution:
  • Deploy WSO2 App Manager to front all the service providers inside the corporate domain. 
  • Configure WSO2 Identity Server as the trusted Identity Provider of the WSO2 App Manager. Both the Identity Server + the App Manager setup we call it as the federation proxy. 
  • Introduce the identity provider running at the hub (it can be another WSO2 Identity Server as well) as a trusted identity provider to the WSO2 Identity Server running as the proxy. 
  • Configure git provisioning against the hub identity provider, configured in WSO2 Identity Server. 
  • For all the service provider, the initial authentication will happen via the hub identity provider and once that is done, configure a connector to the 2nd step to do the account linking. 
  • Products: WSO2 Identity Server 5.0.0+, WSO2 App Manager 

Identity Patterns with the WSO2 Identity Server
Enforce password reset for expired passwords during the authentication flow

Problem:
  • During the authentication flow, enforce to check whether the end-user password is expired and if so, prompt the user to change the password.
Solution:
  • Configure multi-step authentication for the corresponding service provider. 
  • Engage basic authenticator for the first step, which accepts username/password from the end-user. 
  • Write a handler (a local authenticator) and engage it in the second step, which will check the validity of the user’s password and if it is expired then prompt the user to reset the password. 
  • Sample implementation: http://blog.facilelogin.com/2016/02/enforce-password-reset-for-expired.html 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Fine-grained access control for APIs

Problem:
  • Access to the business APIs must be done in a fine-grained manner. 
  • Only the users belong to the business-admin role should be able to access foo and bar APIs during a weekday from 8 AM to 5 PM.
Solution:
  • Setup the WSO2 Identity Server as the key manager of the WSO2 API Manager. 
  • Write a scope handler and deploy it in the WSO2 Identity Server to talk to it’s XACML engine during the token validation phase. 
  • Create XACML policies using the WSO2 Identity Server’s XACML policy wizard to address the business needs. 
  • Products: WSO2 Identity Server 5.0.0+, API Manager, Governance Registr

Identity Patterns with the WSO2 Identity Server
Claim Mapper

Problem:
  • The claim dialect used by the service provider is not compatible with the default claim dialect used by the WSO2 Identity Server. 
  • The claim dialect used by the federated (external) identity provider is not compatible with the default claim dialect used by the WSO2 Identity Server.
Solution:
  • Represent all the service providers in the WSO2 Identity Server and configure the corresponding inbound authenticators (SAML, OpenID, OIDC, WS-Federation). 
  • For each service provider define custom claims and map them to the WSO2 default claim dialect. 
  • Represent all the identity providers in the WSO2 Identity Server and configure corresponding federated authenticators (SAML, OpenID, OIDC, WS-Federation). 
  • For each identity provider define custom claims and map them to the WSO2 default claim dialect. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Identity federation between service providers and identity providers with incompatible identity federation protocols

Problem:
  • The business users need to login into a SAML service provider with an assertion coming from an OpenID Connect identity provider. 
  • In other words, the user is authenticated against an identity provider, which only supports OpenID Connect, but the user needs to login into a service provider, which only supports SAML 2.0.
Solution:
  • Represent all the service providers in the WSO2 Identity Server and configure the corresponding inbound authenticators (SAML, OpenID, OIDC, WS-Federation). 
  • Represent all the identity providers in the WSO2 Identity Server and configure corresponding federated authenticators (SAML, OpenID, OIDC, WS-Federation). 
  • Associate identity providers with service providers, under the Service Provider configuration, under the Local and Outbound Authentication configuration, irrespective of the protocols they support. 
  • Products: WSO2 Identity Server 5.0.0+

Identity Patterns with the WSO2 Identity Server
Single Sign On with delegated access control

Problem:
  • The business users need to login into multiple service providers with single sign on via an identity provider. 
  • Some service providers may need to access backend APIs on behalf of the logged in user. For example, a user logs into the Cute-Cup-Cake-Factory service provider via SAML 2.0 web SSO and then the service provider (Cute-Cup-Cake-Factor) needs to access user’s Google Calendar API on behalf of the user to schedule the order pickup.
Solution:
  • Represent all the service provider in the WSO2 Identity Server as Service Providers and configure inbound authentication appropriately either with SAML 2.0 or OpenID Connect. 
  • For each service provider that needs to access backend APIs, configure OAuth 2.0 as an inbound authenticator, in addition to the SSO protocol (SSO protocol can be SAML 2.0 or OpenID Connect). 
  • Once a user logs into the service provider, either via SAML 2.0 or OpenID Connect, use the appropriate grant type (SAML grant type for OAuth 2.0 or JWT grant type for OAuth 2.0) to exchange the SAML or the JWT token for an access token, by talking to the token endpoint of the WSO2 Identity Server 
  • Products: WSO2 Identity Server 5.0.0+, WSO2 API Manager, WSO2 Application Server 

Identity Patterns with the WSO2 Identity Server
User management upon multi-layer approval

Problem:
  • All the user management operations must be approved by multiple administrators in the enterprise in a hierarchical manner. 
  • When an employee joins the company, it has to be approved by a set of administrators while, when the same employee is assigned to the sales team, must be approved by another set of administrators.
Solution:
  • Create a workflow with multiple steps. In each step specify who should provide the approval. 
  • Define a workflow engagement for user management operations and associate the above workflow with it. 
  • When defining the workflow, define the criteria for its execution. 
  • Products: WSO2 Identity Server 5.1.0+ 

Identity Patterns with the WSO2 Identity Server
Rule-based user provisioning

Problem:
  • The identity admin needs to provision all the employees to Google Apps at the time they join the company. 
  • Provision only the employees belong to the sales-team to Salesforce.
Solution:
  • Represent Salesforce and Google Apps as provisioning identity providers in the WSO2 Identity Server. 
  • Under Salesforce Provisioning Identity Provider Configuration, under the Role Configuration, set sales-team as the role for outbound provisioning. 
  • Under the Resident Service Provider configuration, set both Salesforce and Google Apps as provisioning identity providers for outbound provisioning. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Login to multiple service providers with the current Windows login session

Problem:
  • The business users need to login to multiple service providers supporting multiple heterogeneous identity federation protocols. 
  • Some service providers are on-premise while others are in the cloud. 
  • A user logs into his Windows machine and should be able to access any service provider without further authentication.
Solution:
  • Deploy WSO2 Identity Server over the enterprise active directory as the user store. 
  • Represent all the service providers in the WSO2 Identity Server and configure the corresponding inbound authenticator (SAML, OpenID, OIDC, WS-Federation). 
  • For each service provider, under local and outbound authentication configuration, enable IWA local authenticator. 
  • In each service provider, configure the WSO2 Identity Server as the trusted identity provider. For example, if Salesforce is a service provider, in Salesforce, add WSO2 Identity Server as a trusted identity provider. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Provision federated users to a tenant

Problem:
  • The business users need to login to multiple service providers via multiple identity providers. For example login to Drupal via Facebook or Yahoo! credentials. 
  • Irrespective of the service provider, need to provision federated users to a single tenant (let’s say, individual tenant).
Solution:
  • Define a user store with CarbonRemoteUserStoreManager in the WSO2 Identity Server pointing to the individual tenant. 
  • Represent each federated identity provider in Identity Server. For example, represent Facebook as an identity provider in Identity Server. 
  • Enable JIT provisioning for each identity provider, and pick the user store domain(CarbonRemoteUserStoreManager) to provision users. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Multi-factor authentication for WSO2 Identity Server management console

Problem:
  • Enable MFA for the WSO2 Identity Server Management Console. 
  • In other words, the Identity Server’s Management Console itself must be protected with MFA.
Solution:
  • Introduce WSO2 Identity Server as a service provider to itself. 
  • Under the service provider configuration, configure multi-step authentication having authenticators, which support MFA in each step. 
  • Enable SAML SSO carbon authenticator through the corresponding configuration file. 
  • How-to: http://blog.facilelogin.com/2016/03/enabling-mult-factor-authentication-for.html 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
JIT provision users to cloud service providers

Problem:
  • The company foo has an account with the bar cloud service provider (it can be Google Apps, Salesforce, Workday). 
  • The company foo trusts employees from the company zee to login into the bar cloud service provider, under the foo account. 
  • For example, foo company wants the users from company zee to login into its Google Apps domain.
Solution:
  • Introduce bar as a service provider (bar-sp) to the WSO2 Identity Server running at foo. 
  • Introduce bar as a provisioning identity provider (bar-idp) to the WSO2 Identity Server, and configure the provisioning protocol as supported by bar. For example, if bar is Salesforce, then one can pick the Salesforce provisioning connector. 
  • Introduce the company zee as an identity provider to the WSO2 Identity Server running at foo, and enable JIT provisioning. 
  • Under the bar-sp service provider configuration, under local and outbound authentication configuration, select zee as a federated identity provider. This means, a user who wants to login bar-sp, will be redirected to the zee identity provider for authentication. 
  • Under the bar-sp service provider configuration, under outbound provisioning configuration, select bar-idp as a provisioning identity provider. 
  • Introduce the WSO2 Identity Server running at foo as a trusted identity provider to the zee cloud service provider. For example in Salesforce, add WSO2 Identity Server as a trusted identity provider. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Provision federated users by the identity provider

Problem:
  • The business users need to login to multiple service providers via multiple identity providers. For example login to Drupal via Facebook or Yahoo! credentials. 
  • Irrespective of the service provider, need to group federated users by the identity provider and store all the user attributes locally. For example, the identity admin should be able to find all the Facebook user or the Yahoo users who have accessed the system (i.e. login to any service provider)
Solution:
  • Deploy WSO2 Identity Server over multiple user stores and name each user store after the name of the corresponding identity provider. 
  • Represent each federated identity provider in Identity Server. For example, represent Facebook as an identity provider in Identity Server. 
  • Enable JIT provisioning for each identity provider, and pick the user store domain to provision users. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Multiple login options by service provider

Problem:
  • The business users need to access multiple service providers, where each service provider requires different login options. For example login to Google Apps with username/password, while login to Drupal either with username/password or Facebook. 
  • Enable multi-factor authentication for some service providers. For example login to Salesforce require username/password + FIDO.
Solution:
  • Deploy WSO2 Identity Server over the enterprise user store. 
  • Represent each service providers in Identity Server and under each service provider, configure local and outbound authentication options appropriately. To configure multiple login options, define an authentication step with the required authenticators. 
  • When multi-factor authentication is required, define multiple authentication steps having authenticators, which support MFA in each step. For example username/password authenticator in the first step and the FIDO authenticator in the second step. 
  • If federated authentication is required, for example, login with Facebook, represent all federated identity providers in Identity Server, as Identity Providers and engage them with appropriate service providers under the appropriate authentication step. 
  • In each service provider, configure WSO2 Identity Server as a trusted identity provider. For example in Google Apps, add WSO2 Identity Server as a trusted identity provider. 
  • Products: WSO2 Identity Server 5.0.0+ 

Identity Patterns with the WSO2 Identity Server
Single Sign On between multiple heterogeneous identity federation protocols

Problem:
  • The business users need to access multiple service providers supporting multiple heterogeneous identity federation protocols. 
  • Some service providers are on-premise while others are in the cloud. For example Google Apps (SAML 2.0), Salesforce (SAML 2.0), Office 365 (WS-Federation) are cloud based while JIRA, Drupal, Redmine are on-premise service providers. 
  • A user logs into any of the service providers should be automatically logged into the rest.
Solution:
  • Deploy WSO2 Identity Server over the enterprise user store. 
  • Represent each service provider in the WSO2 Identity Server and configure the corresponding inbound authenticators (SAML, OpenID, OIDC, WS-Federation). 
  • In each service provider, configure WSO2 Identity Server as a trusted identity provider. For example in Google Apps, add WSO2 Identity Server as a trusted identity provider. 
  • Products: WSO2 Identity Server 5.0.0+ 

Enabling Multi-factor Authentication for WSO2 Identity Server Management Console

WSO2 Identity Server Management Console ships with the username/password based authentication. Following explains how to configure MFA.

1. Start WSO2 IS and login as an admin user with username/password, and go to Main --> Identity --> Service Providers --> Add --> fill details appropriately and Register

2. Expand the section Inbound Authenticators --> SAML2 Web SSO Configuration --> Configure. Then complete the SAML configuration as shown in the following image. Set the issuer to carbonServer, Assertion Consumer URL to https://localhost:9443/acs and check Enable Response Signing. Rest keep as defaults.

3. Under Local and Outbound Authentication Configuration, pick Advanced Configuration and define MFA.

4. Shutdown the server and edit the file IS_HOME/repository/conf/security/authenticators.xml and enable SAML2SSOAuthenticator by setting the value of the parameter disabled to false and the value of Priority element to 1.

5. Start the server and visit https://localhost:9443. Now you will notice that the login page has changed with MFA.

Adding OAuth 2.0 Token Introspection Support to WSO2 Identity Server 5.1.0

WSO2 Identity Server 5.2.0 will have the support for OAuth 2.0 token introspection profile. If you are using Identity Server 5.1.0, this blog post explains how to build and deploy the introspection API on IS 5.1.0.

1. Checkout and build the code from https://github.com/facilelogin/aratuwa/tree/master/api-security/org.wso2.carbon.identity.oauth.introspection  and deploy it as a war file in IS 5.1.0 (IS_HOME/repository/deployment/server/webapps/).

2. Restart the Identity Server and now you should be able to use the introspection API.

3. Find below the usage of the introspection API.
 
   Empty token:

   curl -k -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=' https://localhost:9443/introspect

   Response: {"active":false} 
   Invalid token: 

   curl -k -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=Bjhk98792k9hkjhk' https://localhost:9443/introspect 

   Response: {"active":false,"token_type":"bearer"} 
   Get a valid token(replace the value of client_id:client_secret appropriately): 

   curl -v -X POST --basic -u client_id:client_secret -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=client_credentials" https://localhost:9443/oauth2/token 

   Validate the token:

   curl -k -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=99f0a7092c71a6e772cbcf77addd39ea' https://localhost:9443/introspect 

   Response: 
   { "username":"admin@carbon.super", 
     "nbf":3272, 
     "active":true, 
     "token_type":"bearer", 
     "client_id":"LUG28MI5yjL5dATxQWdYGhDLSywa" 
   } 
   Get a valid token with a scope(replace the value of client_id:client_secret appropriately): 

   curl -v -X POST --basic -u LUG28MI5yjL5dATxQWdYGhDLSywa:b855n2UIxixrl_MN_juUuG7cnTUa -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=client_credentials&scope=test1 test2" https://localhost:9443/oauth2/token 

   Validate the token:

   curl -k -H 'Content-Type: application/x-www-form-urlencoded' -X POST --data 'token=c78ac96fe9b59061b53d0223d46ecc24' https://idp1.federationhub.org:9443/introspec  

   Response: 
    { "username":"admin@carbon.super", 
      "scope":"test1 test2 ", 
      "nbf":3240, 
      "active":true, 
      "token_type":"bearer", 
      "client_id":"LUG28MI5yjL5dATxQWdYGhDLSywa" 
    }

A Stateless OAuth 2.0 Proxy for Single Page Applications (SPAs)

1. Build the sample SPA from https://github.com/facilelogin/aratuwa/tree/master/oauth2.0-apps/org.wso2.carbon.identity.oauth.spa

2. Copy the artifact(amazon.war) created from the above step to [CATALINA_HOME]\webapps

3. This sample assumes Apache Tomcat is running on localhost:8080 and WSO2 Identity Server 5.0.0 or 5.1.0 is running on localhost:9443

4. If you use different hostnames or ports, change the hostname and the port inside [CATALINA_HOME]\webapps\amazon\index.html and in.html

5. Also note that the value spaName query parameter in [CATALINA_HOME]\webapps\amazon\index.html it should match the value sample1, which we define later in oauth_proxy.properties, if you change this value make sure you change both the places.

6. Create a service provider in WSO2 Identity Server for the proxy app. Note that this is not for the SPA.

7. Configure OAuth 2.0 as the Inbound Authenticator, with https://localhost:9443/oauth2-proxy/callback as the callback URL. This is pointing to the oauth2-proxy app we are going to deploy in Identity Server later.

8. Create a file with the name oauth_proxy.properties under IS_HOME\repository\conf Add following properties to the file oauth_proxy.properties
    is_server_ep=https://localhost:9443
    client_id=6ktdbCJgmQIqlO1tNiHBQoVelkUa
    client_secret=cg5Gg8PfwI28NjLRy64pyffcK4Ia
    proxy_callback_url=https://localhost:9443/oauth2-proxy/callback
    sp_callback_url_mapping.sample1=http://localhost:8080/amazon/in.html
    sp_logout_url_mapping.sample1=http://localhost:8080/amazon/index.html
    iv=RandomInitVector
    secret_key=Bar12345Bar12345
      9. The value of the client_id and the client_secret should be copied from the service provider you created in Identity Server

      10. The value of the proxy_callback_url should match the callback URL you configured when creating a service provider in Identity Server

      11. The value of sp_callback_url and sp_logout_url should point to the amazon web app running in Apache Tomcat

      12. The properties iv and secret_key are used to encrypt the tokens, set as cookies. The value of iv must be 16 characters long. The value of is_server property must point to the Identity Server.

      13. Build the OAuth 2.0 proxy app from https://github.com/facilelogin/aratuwa/tree/master/oauth2.0-apps/org.wso2.carbon.identity.oauth.proxy and copy target/oauth2-proxy.war to IS_HOME/repository/deployment/server/webapps

      14. Restart the Identity Server. Once everything is done and both Identity Serevr and Apache Tomcat are up and running, you can test this by visiting http://localhost:8080/amazon and clicking on the Login link.