This documentation is for WSO2 Identity Server 5.3.0 . View documentation for the latest release.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction

An Identity Provider (IdP) is responsible for authenticating users  and issuing identification information and authenticating users by using security tokens like SAML 2.0, OpenID Connect, OAuth 2.0 and WS-Trust. This is a favourable alternative to explicitly authenticating a user within a security realm.

The responsibility of the identity provider configuration is to represent external identity providers. These external identity providers can be Facebook, Yahoo, Google, Salesforce, Microsoft Windows Live, etc. If you want to authenticate users against these identity providers, then you must associate one or more federated authenticators with the WSO2 Identity Server. These identity providers support for different authentication protocols. For example, if you want to authenticate users against Salesforce, then you must associate the SAML 2.0 authenticator with the Salesforce identity provider, if you want to authenticate users against Yahoo, then you must associate the OpenID authenticator with it. To make this process much easier, the Identity Server also comes with a set of more specific federated authenticators. For example, if you want to authenticate against Facebook, you do not need to configure OAuth 2.0 authenticator. Instead, you can directly use the Facebook federated authenticator.

...

So, in short, the WSO2 Identity Server allows you to add identity providers and specify various details that help you to link the identity provider to the WSO2 Identity Server. So Therefore, you must specify all information required to send the authentication requests and get a response back from the identity provider. This topic contains the following sections.

Table of Contents
maxLevel3
minLevel3
excludeIntroduction

Adding an identity provider

Follow the instructions below to add a new identity provider.

  1. Sign in. Enter your username and password to log on to the Management Console
  2. Navigate to the Main menu to access the Identity menu. Click Add under Identity Providers.


Fill in the details in the Basic Information section. 
Adding an Identity Provider - Basic InformationImage Modified
Note the following when filling the above form.

Excerpt
FieldDescriptionSample Value
Identity Provider Name

The Identity Provider Name must be unique as it is used as the primary identifier of the identity provider.

FacebookIdP, Twitter
Display Name

The Display Name is used to identify the identity provider. If this is left blank, the Identity Provider Name is used. This is used in the login page when selecting the identity provider that you wish to use to log in to the service provider.

Facebook, Twitter
DescriptionThe Description is added in the list of identity providers to provide more information on what the identity provider is. This is particularly useful in situations where there are many identity providers configured and a description is required to differentiate and identify them.This is the identity provider configuration

...

.
Federation Hub Identity Provider

Select the Federation Hub Identity Provider

...

check-box to indicate if this points to an identity provider that acts as a federation hub. A federation hub is an identity provider that has multiple identity providers configured to it and can redirect users to the correct identity provider depending on their Home Realm

...

identifier or their Identity Provider Name.

...

When we have this check-box selected additional window will pop-up in the multi-option page in the first identity server to get the home realm identifier for the desired identity provider in the identity provider hub.

Selected
Home Realm Identifier

The Home Realm Identifier value can be specified in each federated IDP and can send the Home Realm Identifier value as the “fidp” query parameter (e.g., fidp=googleIdp) in the authentication request by the service provider.

...

The WSO2 Identity Server finds the IDP related to the “fidp” value and redirects the end user to the IDP directly rather than showing the SSO login page. By using this, you can avoid multi-option, in a multi-option scenario without redirecting to the multi-option page.

FB, TW
Identity Provider Public Certificate

The Identity Provider Public Certificate is the public certificate belonging to the identity provider. Uploading this is necessary to authenticate the response from the identity provider. See Using Asymmetric Encryption in the WSO2 Product Administration Guide for more information on how public keys work and how to sign these keys by a certification authority.

This can be any certificate. If the identity provider is another Identity Server, this can be a wso2.crt file.

Note
Expand

...

titleTo create the Identity Provider Certificate

...

click here

Open your Command Line interface, traverse to the <IS_HOME>/repository/resources/security/ directory. Next, you must execute the following command.

Code Block
keytool -export -alias wso2carbon -file wso2.crt -keystore wso2carbon.jks -storepass wso2carbon

Once this command is run, the wso2.

...

crtfile is generated and can be found in the <IS_HOME>/repository/resources/security/ directory. Click Choose File and navigate to this location in order to obtain and upload this file.

See Using Asymmetric Encryption in the WSO2 Product Administration Guide for more information.
Alias

The Alias is a value that has an equivalent value specified in the identity provider that we are configuring. This is required for authentication in some scenarios.

http://localhost:9443/oauth2/token
Expand
titleClick here for more information on the federation hub and the home realm identifier
Info
titleAbout the federation hub and the home realm identifier

The federation hub has multiple identity providers configured to it. In a typical federation hub with multiple identity providers, each identity provider can have a unique home realm identifier that can be used to identify the identity provider you are logging into.

So when a user

...

tries to log in to

...

a service provider

...

following flow will happen,

  • The Identity Server, which this service provider is configured to will find the required federated authenticator from the service provider configuration
  • If this Identity Provider configured as a federation hub, the user can specify the preferred identity provider in the federation hub

...

  • using the multi-option page of the first Identity Server.
  • This information will pass with the authentication request to the federation hub.
  • When the request comes to the federation hub, it is sent to the identity provider that the user specifies from the first identity server. For instance, if the users prefer to use their Facebook credentials to log in, and Facebook is one of the identity providers configured in the federation hub, the user simply has to specify Facebook as the domain in the login screen of first Identity Server.

Image Modified

When the Home Realm Identifier is not specified, you can either select the domain name from a dropdown in the login page, or you have to enter the domain value in a separate page prior to logging in. This can be configured as explained below.

Open the <IS_HOME>/repository/conf/identity/application-authentication.xml file. The ProxyMode configuration allows the framework to operate in either smart mode or dumb mode. In smart mode, both local and federated authentication is supported, while in dumb mode, only federated authentication is supported. If dumb mode is configured here, you must provide the Home Realm Identifier, or you have to display a separate screen to the user to get it.

Image Modified

If smart mode is configured, the default behavior applies, where you can enter a local username and password, or use federated authenticators for authentication.

<ProxyMode>smart</ProxyMode>

Expand
titleClick here for more information on the Alias
Info
titleAbout the Alias

The Alias is used in the following authentication scenario.

Image Modified

Here a SAML identity provider sends a SAML token to a web application for authentication. The SAML token has an audience restriction element that controls access and has a reference to the web application in order to access it. Using this token, the authentication takes place. Now, if the web application needs to access an API that is protected by OAuth 2.0, the same SAML token is sent to the token endpoint of the Identity Server. The Alias value you configure in the Identity Server is associated with this token endpoint. This alias value must be added to the audience restriction element of the SAML token. When this SAML token is sent to the Identity Server, you obtain an access token, which is used to access the API.

So in order to configure this, you must add the SAML identity provider as an identity provider in the Identity Server using the instructions in this topic. When configuring this in the Identity Server, you must specify the token alias for this scenario to work. This indicates that any token coming from the SAML identity provider must have this alias value in the audience restriction element.


  1. Enter the Identity Provider Name and provide a brief Description of the identity provider. Only Identity Provider Name is a required field.
  2. Fill in the remaining details where applicable. Click the arrow buttons to expand the forms available to update.
    Adding Configurations for the Identity Provider

    Expand
    titleClick here for details on how to configure claims

    Include Page
    Configuring Claims for an Identity Provider
    Configuring Claims for an Identity Provider

    Expand
    titleClick here for details on how to configure roles

    Include Page
    Configuring Roles for an Identity Provider
    Configuring Roles for an Identity Provider

    Expand
    titleClick here for details on how to configure federated authenticators

    Include Page
    Federated Authentication
    Federated Authentication

    Expand
    titleClick here for details on how to configure just-in-time provisioning

    Include Page
    Configuring Just-In-Time Provisioning for an Identity Provider
    Configuring Just-In-Time Provisioning for an Identity Provider

    Expand
    titleClick here for details on how to configure outbound provisioning connectors

    Include Page
    Configuring Outbound Provisioning Connectors for an Identity Provider
    Configuring Outbound Provisioning Connectors for an Identity Provider

  3. Click Register to add the Identity Provider.

Configuring a resident identity provider

WSO2 Identity Server can mediate authentication requests between service providers and identity providers. At the same time, the Identity Server itself can act as a service provider and an identity provider. When it acts as an identity provider it is known as the resident identity provider.

The resident identity provider configuration is very relevant for you if you are a service provider and want to send an authentication request or a provisioning request to the Identity Server (say via SAML, OpenID Connect, SCIM, and WS-Trust). See Configuring WS-Trust STSSecurity Token Service for an example of how resident identity provider is used to implement security token service. 

...

  1. Sign in. Enter your username and password to log on to the Management Console.
  2. In the Main menu under the Identity section, click Resident under Identity Providers

    The Resident Identity Provider page appears.

    Enter a Home Realm Identifier for the resident identity provider. You can enter multiple identifiers as a comma separated list.

    Info

    This value is essentially the domain name of the identity provider. If you do not enter a value here, when an authentication request comes to the Identity Server, a page is displayed prompting the user to specify a domain.

    Info

    Idle Session Time Out : This  represents the idle session time out for SSO sessions. The default value is set to 15min which means that if Identity Server does not receive any SSO authentication request for 15min for a given user SSO session would be timeout.  You can configure the idle time out value.

    Remember Me Period :  You can tick on the Remember Me option in Identity Server login page if you need to make remember the SSO session. You can define an expiry time for this remembrance period by configuring Remember Me Period . This is configurable and the default time is 2 weeks.

  3. Configure Optionally, configure inbound authentication if required by setting the Identity Provider Entity Id. This is not mandatory for creating a resident identity provider.
    • Set the Identity Provider If you want to change the default issuer that is localhost to a domain name, you need define the Identity Provider Entity Id under SAML2 Web SSO Configuration. Specifying this gives the tenant identification, so any users provisioned through this tenant can be identified as such.

    • Configure the Security Token Service (STS). You can configure this if you want to secure the WS-Trust endpoint with a security policy.Image Removed

  4. Click Update.
  5. Click Ok to the confirmation message that appears.

Note the following information regarding the URLs on this screen.

Panel
borderColornavyNavy
bgColorPowderBlue
titleColorWhite
borderWidth3
titleBGColorBlackNavy
borderStylesolid
titleAbout URLs

You can modify the host name of these URLs by changing the value in the <IS_HOME>/repository/conf/carbon.xml file using the following configuration.

Code Block
languagexml
themeRDarkEclipse
<HostName>localhost</HostName>

Once you update the host name in the carbon.xml file, change the URL to reflect the new host name hostname in the <IS_HOME>/repository/conf/identity/identity.xml file.

Code Block
languagexml
themeRDarkEclipse
<IdentityProviderURL>https://localhost:9443/samlsso</IdentityProviderURL>

The above URL is used for destination validation of the SAML request. The Identity Server compares the value of the "destination" inside the SAML request with the URL in the above configuration. This is done to ensure that the correct application is communicating with the right identity provider.

SSO URL: https

Info

You can add multiple destination URLs for Identity Server using the Resident Identity Provider UI under "SAML2 Web SSO Configuration". This feature is useful when some SPs directly connect to the IS and some SPs connect through a proxy server.

Image Added



  • SSO URL: https://localhost:9443/samlsso The SAML SSO endpoint of the Identity Provider.
  • Logout URL: https://localhost:9443/samlsso
    The endpoint of the Identity Provider that accepts SAML log out requests.
  • Authorization Endpoint URL: https://localhost:9443/oauth2/authz The Identity Provider's OAuth2/ OpenID Connect authorization end point URL.
  • Token Endpoint URL: https://localhost:9443/oauth2/token The Identity Provider's token end point URL.
  • User Info Endpoint URL: https://localhost:9443/oauth2/token
  • SCIM User Endpoint: https://localhost:9443/wso2/scim/Users
  • SCIM Group Endpoint: https://localhost:9443/wso2/scim/Groups
  • token The end point of the Identity Provider that is used to get the information of the users. The information is gathered by passing an access token.
  • SCIM User Endpoint: https://localhost:9443/wso2/scim/Users
    The Identity Provider's end point for SCIM user operations, such as creating and managing users
  • SCIM Group Endpoint: https://localhost:9443/wso2/scim/Groups
    The Identity Provider's endpoint for the SCIM user role operations, such as creating roles, assigning users to roles, and managing roles.

Exporting SAML2 metadata of the resident IdP

To configure WSO2 Identity Server as a trusted identity provider in a service provider application, export the SAML2 metadata of the resident identity provider of WSO2 IS and import the metadata to the relevant service provider. 

Tip

Use one of the following approaches to do this. 

  1. Expand the Inbound Authentication Configuration section and then expand SAML2 Web SSO Configuration
  2. Click Download SAML2 metadata. A metadata.xml file will be downloaded on to your machine.
  3.  Import the metadata.xml file to the relevant service provider to configure WSO2 Identity Server as a trusted identity provider for your application. 

    Image Added

Managing identity providers

This section provides instructions on how to manage identity providers once they are created.

Viewing identity providers

Follow the instructions below to view the list of identity providers added in the WSO2 Identity Server.

  1. Sign in. Enter your username and password to log on to the Management Console.
  2. In the Main menu under the Identity section, click List under Identity Providers. The list of identity providers you added appears.

Editing identity providers

Follow the instructions below to edit an identity provider's details.

  1. Sign in. Enter your username and password to log on to the Management Console.
  2. In the Main menu under the Identity section, click List under Identity Providers. The list of identity providers you added appears.
  3. Locate the identity provider you want to edit and click on the corresponding Edit link.
  4. You are directed to the edit screen where you can modify the details you configured for the identity provider.

Deleting identity providers

Follow the instructions below to delete an identity provider.

  1. Sign in. Enter your username and password to log on to the Management Console.
  2. In the Main menu under the Identity section, click List under Identity Providers. The list of identity providers you added appears.
  3. Locate the identity provider you want to delete and click on the corresponding Delete link.
  4. Confirm your request in the WSO2 Carbon window. Click the Yes button.

Disabling/Enabling identity providers

Follow the instructions below to disable or enable an identity provider.

  1. Sign in. Enter your username and password to log on to the Management Console.
  2. In the Main menu under the Identity section, click List under Identity Providers. The list of identity providers you added appears.
  3. Locate the identity provider you want to delete and click on the corresponding Disable link to disable the identity provider. Clicking this link will change the link to Enable. To enable the identity provider again, click the Enable link.
  4. Click Ok on the confirmation form that appears when clicking Disable/Enable.
     
Panel
titleRelated Topics

See the following topics for information on configuring service providers using different specifications.

See the following topics to configure different applications as service providers in Identity Server.