/
Adding and Configuring a Service Provider
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

Adding and Configuring a Service Provider

This topic provides instructions on how to add a new service provider. You must provide configuration details to add this service provider in the WSO2 Identity Server so that the authentication and/or provisioning happens as expected. For more information on how the service provider fits into the WSO2 IS architecture, see Architecture.

The responsibility of the service provider configuration is to represent external service providers. The service provider configurations cover the following:

  • Define how the service provider talks to the Identity Server inbound authenticator
    This is via inbound authenticators. When you register a service provider, you need to associate one or more inbound authenticators with it.
  • Define how to authenticate users.
    This can be via a local authenticator, request-path authenticator or federated authenticator. Based on this configuration, the Identity Server knows how to authenticate the user when it receives an authentication request (via an inbound authenticator) and based on the service provider who initiates it.
  • Maintain claim mapping.
    This is to map the service provider's own set of claims to the Identity Server's claims. For example, WSO2 Identity Server (WSO2 IS) has a claim called work email ( http://wso2.org/claims/emails.work ) but your service provider application expects to receive a value named email. If the service provider application receives a value named work email, it does not recognize it as it does not recognize it. Therefore, to ensure that the values sent by WSO2 IS is understood and recognized by the service provider application, you can use claim mapping.
    When the authentication framework hands over a set of claims (which it gets from the local user store or from an external identity provider) to the response builder of the inbound authenticator, the framework talks to the service provider configuration component, find the claim mapping and do the claim conversion. See  Configuring Inbound Authentication for a Service Provider  for more information about response builder. Now the response builder will receive the claims in a manner understood by the corresponding service provider. Read more about claim management.

This topic contains the following sections.

Adding a service provider

Note: This section only describes how to add a service provider using the Management Console. Instead of adding a service provider via the management console, it is also possible to add a service provider using a configuration file as described  here .

  1. Log in to the Management Console
  2. Navigate to the Main menu to access the Identity menu. Click Add under Service Providers.
  3. Fill in the Service Provider Name and provide a brief Description of the service provider. Only Service Provider Name is a required field.

    The Service Provider Name should not contain any special characters except for fullstops (.), hyphens (-), underscores (_) and spaces.

  4. Click Register to add the new service provider.

    Note: When a service provider is created, it is assigned to a "APPLICATION" role (for instance, if you add Travelocity as the service provider, then the role will look like "Application/travelocity"). Users who wish to manage the created service provider should have this application role assigned. See Configuring Roles for guidance on how to do this.

  5. The Service Providers screen appears. Paste the application's certificate to the Application Certificate field.  

    When is this certificate used

    This certificate is used to validate the signatures of the signed requests from the application (service provider) to the Identity Server. Therefore, the certificate is used in below scenarios:


    Format of the certificate

    WSO2 IS expects the certificate to be in PEM format.

    PEM is a Base64 encoded format, therefore contains ASCII character and easier to deal with rather than a binary encoded certificate.


    How to obtain the PEM encoded certificate

    The PEM content of a certificate in a JKS file, can be obtained by following the steps below:

    1. Export the certificate from the keystore. The exported certificate will be in binary format.

    keytool -export -keystore <keystore-path> -alias <alias-of-the-certificate> -file <path-of-the-expected-certificate-file>
    
    e.g. keytool -export -keystore wso2carbon.jks -alias wso2carbon -file wso2carbon.crt

    2. Convert the above binary encoded certificate to a PEM encoded certificate

    openssl x509 -inform der -in <path-of-binary-certificate> -out <path-of-expected-pem-content>
    
    e.g. openssl x509 -inform der -in wso2carbon.crt -out wso2carbon.pem


    Note: You can paste the public certificate in to the given text area or upload file in PEM format. If the Application Certificate field is left blank, WSO2 IS is backward compatible and follows the previous implementation to locate the certificates in the keystore.
    This means that if it is a SAML SSO flow, the certificate alias mentioned in SAML inbound authentication configuration is used when the certificate is not updated via the management console. If it is an OIDC request object signature validation, the certficate will be retrived from default keystore, aliase to consumer key of the auth application.

  6. Select if the service provider is a SaaS Application or not using the Saas Application checkbox. The SaaS Application configuration defines which users you want to be able to log into your web application.

    Tip: By default, the SaaS Application check box is disabled, which means the web application is not shared among tenants so only users in the current tenant (the one you use to define the service provider) will be allowed to log into the web application. Alternatively, if you enabled the SaaS Application check box, that means this web application is shared among tenants so users from any tenant will be allowed to log into the web application. For example, if there are three tenants, namely TA, TB and TC and the service provider is registered and configured only in TA.

    • If the SaaS Application configuration is disabled, only users in TA are able to log into the web application.

    • If the SaaS Application configuration is enabled, all TA, TB, TC users are able to log into the web application.

    • For more information on creating and managing tenants, see Creating and Managing Tenants.

 Click here for details on how to configure claims

Claim mapping for a service provider involves mapping claims that are used by the service provider to the claims local to the WSO2 Identity Server. For the occasions where a service provider needs some information of the user from the Identity Server where the service provider authenticates, the claim mapping is useful. Once the user is authenticated, the service provider can use these received claim details to provide its service.  See the Identity Server Architecture for more information on how claim mapping fits in to the overall scheme of things.

Claim mapping

  1. In the Claim Configuration form, s elect the claim mapping dialect by either choosing to use a local claim dialect or define your own custom claim dialect.
    • If you choose to Use Local Claim Dialect, you need to fill in the following details.
      1. Fill in your requested claims by clicking the Add Claim URI button.
      2. Choose your Local Claim from the drop-down.  Select whether this claim is a Mandatory Claim for the Service Provider using the checkbox.
    • If you choose to Define Custom Claim Dialect, you need to do the following. 
      1. Add a custom claim URI by clicking on the Add Claim URI button. Clicking this button again enables you to map more claims.

      2. Add the Service Provider Claim and choose the corresponding Local Claim from the drop-down. Select whether you want the claim to be a Requested Claim and  whether this claim is a Mandatory Claim for the service provider, using the relevant checkboxes.

         Click to view vital information when configuring claims for an OpenID Connect Service Provider

        Note: When mapping custom claims for a service provider configured with OpenID Connect, ensure to map the custom claims in the SP configuration as seen in the screenshot above AND also add the custom claims to a scope value in the oidc file.

        Why?

        This is required because OpenIDConnect claim scopes are supported from WSO2 IS 5.2.0 onwards. This means that when you request for an OIDC token, you can specify a single scope value that is bound to a set of multiple claims. When that OIDC token is sent to the UserInfo endpoint, only the claims which are common in both the OIDC scope config file and the SP claim configuration (i.e., the intersection of claims in both these configurations) will be returned.

        To do this,

        1. Click on Browse under Registry on the Main tab of the management console.
        2. Navigate to /_system/config/ and click on the oidc file. Expand the Properties section.
        3. Add the custom claims to the existing default scope openid by clicking on Edit. Alternatively, add a new scope for the custom claims by clicking on Add New Property and send it when getting the OIDC token along with the mandatory openid scope.

        OIDC considers address as a JSON object. Therefore, if you want to pass an address using a different claim other than the address claim that is already available, you can do it using any of the following methods:

        In here we do not have to add values in complex object format. Just need to put values as street

        • Without using the address. prefix.
          For this, you need to register a scope named address in the WSO2 Identity Server's registry and add the value as the street or lane or any preferred value.
        • Create a new external claim using the address. prefix.
          Let's a look at how to create a new claim for the address. prefix.
          1. Click Add under Claims.
          2. Click Add External Claim.
          3. Select http://wso2.ord/oidc/claim as the value for Dialect URI.
          4. Enter address.street as the value for External Claim URI.

            You can enter any value with the prefix address., such as address.country, address.lane, and much more.

          5. Map the claim you are creating to any claim within WSO2 Identity server.
            For example, you can map it to http://wso2.org/claims/location.

        Now you can see the claim you created being listed. It is created as a JSON object in WSO2 Identity Server.

         Click to view vital information when configuring claims for an SAML2 Service Provider

        Note: When mapping custom claims for a service provider configured with SAML2, ensure to select both "Enable Attribute Profile" and " Include Attributes in the Response Always" from the SAML2 service provider configuration as follows.

        Why?

        This is required since Identity Server include user claims in the SAML2 response only if SAML2 attribute profile is enabled.

        Information on mapping claims

        The Local Claim list includes a set of standard claim values which are local to the WSO2 Identity Server. When adding a service provider, it is necessary to map the values of the claims local to the service provider with those provided in this drop-down list which are local to the Identity Server. This should be done for all values in the service provider unless they use the same claim name.

        Marking a claim as a Mandatory Claim would ensure that the WSO2 IS will definitely send a value for this claim to the service provider.  When a user logs into this service provider, if the identity provider does not provide a value for any of the mandatory claims, the user will be prompted to provide them at the time of login.
         

         Expand for steps to test out mandatory claims

        Testing mandatory claims

        To test out mandatory claims,

        1. Configure the travelocity sample application by following the steps in the Configuring Single Sign-On topic.

        2. Configure a few claims and select the checkbox for mandatory claims.

        3. Ensure that there are one or more claims which are missing in the user profile of the user you wish to login with.

        4. Run the travelocity sample and try the SAML login.

        5. Log in with the user credentials of the user who has a few mandatory claims missing, and click Submit.
        6. A claim request will be prompted. At this point, the mandatory claim rule is enforced and you cannot proceed without providing the necessary claim values. Provide the necessary claim values and click Submit.
        7. You will be successfully logged in to the application.

        Marking a mapped claim as a Requested Claim would ensure that the service provider definitely sends this claim to the Identity Server. This is useful particularly in cases where there are hundreds of claims and only specific ones need to be sent to the Identity Server.

        Collecting consent for requested and mandatory claims

        When the user is authenticated to the application, claims that are indicated as required and/or mandatory in this claim configuration form will be displayed in the consent request UI to prompt for the user’s consent. If a claim is indicated as a mandatory claim, it will be indicated with a red color asterix (*) when requesting consent. The user will not be able to proceed with authentication without providing consent for the mandatory claims.


        For more information about consent management during authentication, see Consent Management with Single-Sign-On.

  2. Select the Subject Claim URI and the Role Claim URI (for custom claims)from the drop-down. The claims you mapped are listed in the drop-down and you can choose among these claims.

    • Subject Claim URI defines the authenticated user identifier which will return with the authentication response to the service provider.
    • Role Claim URI defines the role claim for the service provider. This is useful if you use a different claim as the role claim or if you define a custom claim mapping for the service provider.

Caching service provider claims

If you want to cache claim data, be sure to add a cache configuration similar to the following under <CacheManager name="IdentityApplicationManagementCacheManager"> in the <IS_HOME>/repository/conf/identity/identity.xml file:

<Cache name="LocalClaimInvalidationCache" enable="true" timeout="300" capacity="5000" isDistributed="false"/>

Here, you need to specify values as follows:

  • timeout: The cache timeout value in seconds.
  • capacity: The maximum cache size.
  • isDistributed: Set this to false.
Related Topics

 Click here for details on how to configure roles and permissions

WSO2 Identity Server (WSO2 IS) allows you to configure and manage roles as well as permission for a service provider.

When you create a service provider via WSO2 IS, a corresponding application role is created by default within WSO2 IS. For example, if you create a service provider named SP1, a corresponding application role is created for SP1 within WSO2 IS, and that application role is assigned to the user who created the service provider. Therefore, only the user who creates a service provider can view or manage the service provider. If you want to allow any other user to be able to view or manage a service provider, the user has to be assigned the application role corresponding to the particular service provider.

Application Role: A special case of internal role that is created for a particular service provider application. Only users who are assigned the application role permission can manage the corresponding service provider application.

Now, let's create a service provider, and then configure roles and permission for the created service provider. 

Next, follow the steps below to configure roles and define custom permission for the service provider:

  1. In the service provider that you created, expand the Role/Permission Configuration section, and then expand the Permissions as well as the Role Mapping sections.
  2. Click Add Permission and specify the service provider specific permission that you want to add. 

    • If you want to add another permission entry, click Add Permission again.
    • If you want to delete an entry, click Delete.

    Once you add/update service provider specific permission details, the permission details will be listed as available permission when adding roles via WSO2 IS.

  3. Click Add Role Mapping and enter appropriate values for the Local Role as well as the Service Provider Role

    • If you want to add another role mapping entry, click Add Role Mapping again.
    • If you want to delete a role mapping entry, click Delete.

    When you add role mapping, you can map an exact role name available in WSO2 IS to a particular service provider role.

Now that you have configured roles and permission for the service provider, you can go ahead and assign the application role permission to any user who should be able to view and manage the service provider. For information on how to assign roles to a user, see Configuring Users.

 Click here for details on how to configure inbound authentication

The responsibility of the inbound authenticator component is to identify and parse all the incoming authentication requests and then build the corresponding response. A given inbound authenticator has two parts:

  • Request Processor
  • Response Builder

For each protocol supported by the WSO2 Identity Server, there should be an inbound authenticator. The Identity Server includes inbound authenticators for SAML 2.0, OpenID Connect, OAuth 2.0, Kerberos KDC, WS-Trust STS and WS-Federation (passive). The responsibility of the SAML 2.0 request processor is to accept a SAML request from a service provider, validate the SAML request and then build a common object model understood by the authentication framework and handover the request to it. The responsibility of the SAML response builder is to accept a common object model from the authentication framework and build a SAML response out of it.

Both the request processors and the response builders are protocol aware, while the authentication framework is not coupled to any protocol. See Architecture for more information on the complete flow where inbound authenticators come into play.

You can configure the following for inbound authentication.

Removed Feature!

OpenID 2.0 has been removed from the base product in WSO2 Identity Server version 5.3.0 onwards as it is now an obsolete specification and has been superseded by OpenID Connect. Alternatively, we recommend that you use OpenID Connect. 

 SAML2 Web SSO Configuration

  1. Expand the SAML2 Web SSO Configuration and click Configure.
  2. Select one of the following modes:

Metadata and URL configuration

When configuring a service provider (SP) or a federated identity provider (Federated IdP), the user is required to enter configuration data to facilitate exchanging authentication and authorization data between entities in a standard way. Apart from manual entering of configuration data, WSO2 IS allows you to upload configuration data using a metadata XML file or refer to a metadata XML file located in a predetermined URL. These two methods of uploading configuration data enable faster entry of configuration data because it allows the user to use the same metadata xml file for multiple instances of entity configuration. In addition to SAML metadata upload, WSO2 IS also supports SAML metadata download for the resident identity provider.

Manual configuration

  1. Select Manual Configuration and fill in the form that appears.
  2. Click Register.

The following points should be taken into consideration when filling the above New Service Provider form.

FieldDescriptionSample value
IssuerSpecify the Issuer. This is the <saml:Issuer> element that contains the unique identifier of the service provider. This is also the issuer value specified in the SAML Authentication Request issued by the service provider. When configuring single-sign-on across Carbon servers, ensure that this value is equal to the ServiceProviderID value mentioned in the <IS_HOME>/repository/conf/security/authenticators.xml file of the relying party Carbon server.travelocity.com
Assertion Consumer URLsSpecify the Assertion Consumer URLs. This is the URL to which the browser should be redirected to after the authentication is successful. This is the Assertion Consumer Service (ACS) URL of the service provider. The identity provider redirects the SAML2 response to this ACS URL. However, if the SAML2 request is signed and SAML2 request contains the ACS URL, the Identity Server will honor the ACS URL of the SAML2 request. It should have this format: https://(host-name):(port)/acs. You can add multiple assertion consumer URLs for the service provider by entering the URL and clicking the Add button.http://wso2is.local:8080/travelocity.com/home.jsp
Default Assertion Consumer URL

Since there can be multiple assertion consumer URLs, you must define a Default Assertion Consumer URL in case you are unable to retrieve it from the authentication request.

Tip: In a service provider initiated single sign-on setup, the following needs to be considered.

  • If no ACS URL is given in the <AuthnRequest>, the Identity Server sends the response to the default ACS URL of the service provider (whether the request is signed or not).
  • If the ACS URL in <AuthnRequest> matches with one of the registered URLs, the Identity Server sends the response to the matched one. 
  • If the ACS URL in <AuthnRequest> does not match any of the registered ACS URLs and if the request is signed, the Identity Server sends the response to the ACS URL in the request only if the signature is valid. Alternatively, the <AuthnRequest> is rejected.

In an identity provider initiated single sign-on setup, the following needs to be considered.

  • If the “acs” query parameter is not present in the request, the Identity Server sends the response to default ACS URL of the service provider.
  • If the "acs” parameter is present and the value of that parameter matches with any of the registered ACS URLs of the service provider, then the Identity Server sends the response to the matched one.
http://wso2is.local:8080/travelocity.com/home.jsp
NameID format

Specify the NameID format. This defines the name identifier formats supported by the identity provider. The service provider and identity provider usually communicate with each other regarding a specific subject. That subject should be identified through a Name-Identifier (NameID) , which should be in some format so that It is easy for the other party to identify it based on the format. Name identifiers are used to provide information regarding a user. 

About NameID formats

For SSO interactions, you can use the following types of NameID formats.

  • urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
  • urn:oasis:names:tc:SAML:2.0:nameid-format:transient
  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
  • urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
  • urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName
  • urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName
  • urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos
  • urn:oasis:names:tc:SAML:2.0:nameid-format:entity

This specifies the name identifier format that the Identity Server wants to receive in the subject of an assertion from a particular identity provider. The following is the default format used by the identity provider.

  • urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Certificate Alias

Select the Certificate Alias from the dropdown. This is used to validate the signature of SAML2 requests and is used to generate encryption. Basically the service provider’s certificate must be selected here. Note that this can also be the Identity Server tenant's public certificate in a scenario where you are doing a tenant specific configuration.

From WSO2 IS 5.5.0 onwards, the .pem certificate can be updated via the Service Provider screen in the management console UI using the Application Certificate field. If the certificate has been entered in the Application Certifiate field, the system will use the certificate given there and override the certificate alias field.

However, if the Application Certificate field has been left blank, the certificate specified in Certificate Alias will be used.

wso2carbon
Response Signing Algorithm

Specifies the ‘SignatureMethod’ algorithm to be used in the ‘Signature’ element in POST binding. The default value can be configured in the <IS_HOME>/repository/conf/identity.xml file, in the SSOService element with SAMLDefaultSigningAlgorithmURI tag. If it is not provided the default algorithm is RSA­SHA 1, at URI ‘ http://www.w3.org/2000/09/xmldsig#rsa­sha1' .

http://www.w3.org/2000/09/xmldsig#rsa­sha1 
Response Digest Algorithm

Specifies the ‘DigestMethod’ algorithm to be used in the ‘Signature’ element in POST binding. The default value can be configured in the <IS_HOME>/repository/conf/identity.xml file, in the SSOService element with SAMLDefaultDigestAlgorithmURI tag. If it is not provided the default algorithm is SHA 1, at URI ‘ http://www.w3.org/2000/09/xmldsig#sha1 .

http://www.w3.org/2000/09/xmldsig#sha1
Assertion Encryption AlgorithmThe algorithm that the SAML2 assertion is encrypted. The default value can be configured in the <IS_HOME>/repository/conf/identity.xml file, in the SSOService element with SAMLDefaultAssertionEncryptionAlgorithm URI tag. The default is http://www.w3.org/2001/04/xmlenc#aes256-cbc.www.w3.org/2001/04/xmlenc#aes256-cbc
Key Encryption AlgorithmThe algorithm that the SAML2 key is encrypted. The default value can be configured in the <IS_HOME>/repository/conf/identity.xml file, in the SSOService element with SAMLDefaultKeyEncryptionAlgorithm URI tag. The default algorithm is http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
Enable Response SigningSelect Enable Response Signing to sign the SAML2 Responses returned after the authentication process.Selected
Enable Signature Validation in Authentication Requests and Logout Requests Select Enable Signature Validation in Authentication Requests and Logout Requests if you need this functionality configured. This specifies whether the identity provider must validate the signature of the SAML2 authentication request and the SAML2 logout request that are sent by the service provider. Unselected
Enable Assertion Encryption