Managing Identity Providers

Managing Identity Providers

An Identity Provider (IdP) manages accounts for users who may need secure access to the applications or services. A Service Provider (SP) is the server receiving request from a user for access to a service or application. In a typical SAML flow, when a user requests a service from the SP, the SP first requests and obtains an identity assertion from the IdP. The IdP receives the request from SP and generates an identity assertion based on the user account information. SP then decides whether to perform the service based on assertion provided by IdP. UAA supports SAML protocol for communicating with IdPs or SPs.

You can configure your UAA instance to act as an IdP or use an external IdP. The following scenarios determine the type of configuration you need for your UAA:
  • If you administer users accounts locally in UAA using UAA SCIM APIs or UAA dashboard, then UAA is your default identity provider. You do not need any additional configuration for identity provider in UAA.
  • If you provision your user accounts remotely on an external IdP such as Company SSO, you can configure UAA as SP that redirects to external IdP. For more information, see Configuring UAA as Service Provider for External Identity Provider.
  • If you have applications that provide SP capability (For example, GitHub Enterprise or ServiceNow), you can configure UAA as IdP. For more information, see Configuring UAA as an Identity Provider.
  • It is possible to configure UAA as both SP and IdP. However such a configuration is useful only as a test environment. To set up UAA as SP and IdP, you can complete steps for configuring UAA as both SP and IdP.

Configuring UAA as Service Provider for External Identity Provider

If you provision your user accounts remotely on an Identity Provider (IdP) such as Company SSO, you can configure UAA as Service Provider (SP) that redirects to external IdP.

Before You Begin

  • Obtain your Identity Provider (IdP) metadata from your IdP administrator.
  • Log In to Predix.io and go to Console view.

About This Task

Complete the following procedure to configure UAA as SP for external IdP:

Procedure

  1. In the Services Instances page on Predix.io, select the UAA instance that you need to configure.
  2. Select the Configure Service Instance option.
  3. In the UAA Dashboard login page, specify your admin client secret and click Login.
  4. In UAA Dashboard, click on the Identity Providers tab.
  5. In the External Identity Provider section, select New Identity Provider.
  6. In the New Identity Provider form, specify the following information and press Submit:
    Name of the FieldDescription
    NameSpecify the name of your IdP.
    DescriptionSpecify a short description for your IdP.
    TypeSelect the type of IdP- SAML or OIDC.
    Email DomainSpecify the email domain that UAA can use to identify the identity provider if you have configured more than one identity provider. To support this feature, UAA provides a configuration of IdP discovery. By default, this configuration is set to False.

    UAA can be configured to set IDP Discovery to true if you have configured more than one identity provider. For more information, see uaas-managing-identity-providers.html#task_64ea2282-0cac-4bbc-a838-542690b157a3

    ActiveSelect this option to set the IdP as active. If you have multiple IdPs defined for a single UAA instance, UAA interacts with only active IdPs. If you have multiple active IdPs for a single UAA instance, you must ensure that the clients related to the IdPs are updated with the corresponding information. Although it is possible to update a single client to interact with multiple IdPs, as a best practice, you can define a new client for each of your application to interact with UAA.

    If you are setting up an OpenID Connect (OIDC) IdP, the following field are available:

    Name of the FieldDescription
    Username MappingSpecify the username attribute defined in your IdP.
    Authorization Endpoint UrlSpecify the authorization endpoint for OIDC token.
    Token Endpoint UrlSpecify the token URL for OIDC authorization code.
    Token Key Endpoint UrlSpecify the token key endpoint for token verification.
    Token IssuerSpecify the URL of your OIDC provider.
    Relying Party Client IDSpecify the OIDC provider client id.
    Relying Party Client SecretSpecify the OIDC provider client secret.
    Automatically create a shadow user on loginSelect this option to create a local user in UAA corresponding to each user defined in the identity provider that you are configuring. The local user is created when the user logs-in for the first time. This feature enables a user to be authenticated by UAA without requiring you to create it in UAA also.

    By default this option is turned off. You must create each user in UAA even if the user exists in IdP for authentication from UAA.

    This option is useful if you need to white list users to authenticate only a subset of users setup in your identity provider. To white list users, you can turn this option off while configuring a new IdP, and individually create users in UAA corresponding to users that are defined in your IdP that you need authenticated.

    If you are setting up a SAML IdP, the following fields are available:

    Name of the FieldDescription
    Name ID FormatSpecify the IdP ID format that UAA SP must use. This is useful if the IdP metadata contains multiple ID formats and you need to specify the format that SP must use. You can copy the ID format string from the metadata that you specify.
    MetadataSpecify the IdP metadata and download the UAA SP metadata in this field. You must obtain the IdP metadata from your IdP administrator. You must supply the UAA SP metadata to your IdP administrator.
    Email(Optional) Specify the attribute defined in your IdP that corresponds to the email attribute in UAA.
    Given Name(Optional) Specify the attribute defined in your IdP that corresponds to the Given Name attribute in UAA.
    Family Name(Optional) Specify the attribute defined in your IdP that corresponds to the Family Name attribute in UAA.
    Automatically create a shadow user on loginCreates a local user in UAA corresponding to each user defined in the identity provider that you are configuring. The local user is created when the user logs-in for the first time. This feature enables a user to be authenticated by UAA without requiring you to create it in UAA also.

    If this option is turned off, you must create each user in UAA even if the user exists in IdP for authentication from UAA.

    This option is useful if you need to white list users to authenticate only a subset of users setup in your identity provider. To white list users, you can turn this option off while configuring a new IdP, and individually create users in UAA corresponding to users that are defined in your IdP that you need authenticated.

    The IdP is displayed in the list of Identity Providers.
  7. To set up the client for the IdP to access UAA, click on the View/Edit option next to the name of your IdP.
  8. Specify a client for your IdP.

    You can either choose an existing client or create a new client. As a best practice for development, you can add a new client for each application.

    To create a new client, click on the Create new client for this IDP option. By default, the Create Client form is populated for grant type Authorization Code. You can update it to use implicit or password grant types also. For client credentials grant type, you must first create a user.

    For more information on creating a client, see uaas-managing-clients.html#task_79a81b74-552e-4f74-abfc-bd37e6adac87.

Configuring UAA as a Service Provider Using Scripts

As an optional procedure, you can use UAAC and configuration scripts instead of UAA Dashboard to configure UAA as a service provider.

Before You Begin

  • Download the following scripts from GitHub.
    • create-saml-idp.sh
    • create-client-for-idp.sh

About This Task

You can configure UAA as Service Provider (SP) that redirects to external Identity Provider (IdP) such as Company SSO.

You can use the UAA command-line interface (UAAC), to manage your UAA instance. For more information on installing the command-line interface, see https://github.com/cloudfoundry/cf-uaac.

Procedure

  1. Specify your UAA instance as the intended target.
    uaac target <uaa_instance_url>

    <uaa_instance_url> is the URL to your trusted issuer, for example, https://11fa0273-9e2a-37e2-9d06-2c95a1f4f5ea.predix-uaa.run.aws-usw02-pr.ice.predix.io. You can retrieve this URL from the VCAP_SERVICES environment variable after binding your UAA instance to an application.

  2. Log in using the administrative client.
    uaac token client get admin
  3. Specify the administrative client secret at the prompt.
  4. Export SAML Service Provider metadata from UAA. Provide this metadata to your IdP administrator so it can be imported into the IdP.

    The uaa-sp-metadata.xml file is the Service Provider SAML metadata generated by your UAA instance. It is available at the following endpoint:

    <uaa_instance_url>/saml/metadata/alias/<uaa_instance_guid>.cloudfoundry-saml-login

    For example,

    https://13fa0384-9e2a-48e2-9d06-2c95a1f4f5ea.predix-uaa.run.aws-usw02-pr.ice.predix.io/saml/metadata/alias/13fa0384-9e2a-48e2-9d06-2c95a1f4f5ea.cloudfoundry-saml-login
  5. Your IdP administrator will configure their IdP, import the SAML Service Provider metadata, and generate the Identity Provider metadata. Obtain this Identity Provider metadata from your IdP administrator. You need to import this metadata into UAA.
  6. Validate the SAML Identity Provider metadata by running through a XML parser. Ensure that it contains a valid XML header such as:
    <?xml version="1.0" encoding="UTF-8"?>

    If your file does not contain the required header, add it to the top of your metadata file.

  7. Create the SAML Identity Provider for the specified UAA instance using the create-saml-idp.sh script. The script uses the specified SSO metadata file. 
    ./create-saml-idp.sh -n <my-idp-name> -m <idp-metadata>.xml -a -c <mapping-config-file> -g <groups-config-file>

    • -n specifies a name for your identity provider.

    • -mspecifies the SSO metadata provided by your IdP administrator. For example, idp-metadata.xml

    • -a specifies that a shadow user should be created in UAA. By default, a shadow user is not created. Using the -a option is required when you set up the identity provider for the first time.
    • -c is an optional parameter that specifies configuration mapping file. A configuration mapping file contains attribute mappings required to convert SAML assertion attributes to JWT token.
      An example of configuration mapping file is as follows:
      {
 "email":"mail",
 "given_name":"first name",
 "family_name":"last name"
 }
    • -g is an optional parameter that specifies groups configuration file. A groups configuration file contains any groups that need to be mapped from external IdP.
      An example of groups configuration file is as follows:
      [
"group1",
"group2",
"group3",
"group4",
"group5"
]

    For example, to use GE SSO, you can specify:

    ./create-saml-idp.sh -n gesso-staging-idp -m gesso-staging-idp-metadata.xml -a
    Note: If required, you can update the IdP configuration after configuring UAA for your IdP. For more information, see Updating IdP Configuration.
  8. Validate that the identity provider that you specified is present.
    uaac curl /identity-providers
  9. Use the create-client-for-idp.sh script to create a client with the specified identity provider (IdP) as the allowed provider for the client. Each OAuth client can specify one or more identity providers responsible for authenticating the user. The default identity provider is uaa, which means users are authenticated using the UAA login page. Use this script to specify a different identity provider for user login, such as a SAML identity provider. However, it does not allow you to specify multiple identity providers.
    ./create-client-for-idp.sh -c <client_id> -s <client-secret> -p <my-sso-idp> -r <redirect_uri>
    • -c specifies the client Id.
    • -s specifies the client secret.
    • -p specifies a name for your identity provider.
    • -r specifies your applications URI.

    For example, 

    ./create-client-for-idp.sh -c apm_app -s changeme -p gesso-staging-idp -i  -r Predix-HelloWorld-WebApp-myapp.run.aws-usw02-pr.ice.predix.io
  10. Validate that your client is present and allowed providers attribute is set to your IdP.
    uaac client get <client_id>

Results

To test your setup, use the following URL: 

<uaa_instance_url>/oauth/authorize?client_id=<my_app>&response_type=code&redirect_uri=<redirect_uri>
Note: Use this URL for testing if you are using the Authorization Code authorization grant.
  • <client_id> is the name of the client provisioned in the step 6
  • redirect_uri is the application URL. For example, https://security-predix-seed.grc-apps.svc.ice.ge.com.

The request is redirected to your IdP login page where you can enter the credentials for user that you provisioned for your IdP. If login is successful, you are redirected back to redirect_uri.

Note: Use browser plugin tools such as SAML Tracer for Firefox to validate SAML flow.

Updating IdP Configuration

Before You Begin
  • Download the following scripts from GitHub.
    • update-saml-idp.sh
About This Task
You can update UAA configuration to reflect any changes to your IdP setup.
Procedure
  1. Specify your UAA instance as the intended target.
    uaac target <uaa_instance_url>

    <uaa_instance_url> is the URL to your trusted issuer, for example, https://11fa0273-9e2a-37e2-9d06-2c95a1f4f5ea.predix-uaa.run.aws-usw02-pr.ice.predix.io. You can retrieve this URL from the VCAP_SERVICES environment variable after binding your UAA instance to an application.

  2. Log in using the administrative client.
    uaac token client get admin
  3. Specify the administrative client secret at the prompt.
  4. Update the SAML Identity Provider for the specified UAA instance using the update-saml-idp.sh script. The script uses the specified SSO metadata file. 
    ./update-saml-idp.sh -n <my-idp-name> -m <idp-metadata>.xml -d <idp-id> -a -c <mapping-config-file> -g <groups-config-file>
    • -n specifies the name of identity provider that you specified while creating the IdP and it corresponds to the name attribute for /identity-providers payload.
    • -d specifies the IdP Id. IdP Id is auto generated id from UAA and corresponds to id attribute for /identity-providers payload.
    • For description of other parameters, see uaas-managing-identity-providers.html#task_9e728b94-1119-4846-8dd4-b023a38be2d9.

Identifying IdP Using Email Domain

You can configure UAA to use the email domain to identify the identity provider if you have configured more than one external identity providers.

About This Task

When a user logs in using a set email Id, UAA can redirect the call to the right identity provider if multiple identity providers are present. To configure UAA to identify the identity provider, you set the IdP discovery configuration in UAA. By default, this configuration is set to False.

Procedure

  1. In UAA Dashboard, select the Customization tab.
  2. In the Customization page, turn on the Enable IDP Discovery option.
  3. Click Save.

Configuring UAA as an Identity Provider

If you have applications that provide Service Provider (SP) capability (For example, GitHub Enterprise or ServiceNow), you can configure UAA as an Identity Provider (IdP).

Before You Begin

  • Obtain your SP metadata from your administrator.
  • Log In to Predix.io and go to Console view.

About This Task

Complete the following procedure to configure UAA as SAML IdP to integrate with other service providers.

Procedure

  1. In the Services Instances page on Predix.io, select the UAA instance that you need to configure.
  2. Select the Configure Service Instance option.
  3. In the UAA Dashboard login page, specify your admin client secret and click Login.
  4. In UAA Dashboard, click on the Identity Providers tab.
  5. In the UAA as Identity Provider section, select New Service Provider.
  6. In the New Service Provider form, specify the following information and press Submit:
    Name of the FieldDescription
    NameSpecify the name of your SP.
    Entity IDSpecify the Entity ID for your SP. This value must match the value in the SP metadata.
    ActiveSelect this option to set the the SP as active. If you have multiple SPs defined for a single UAA instance, UAA interacts with only active SPs. If you have multiple activeSPs for a single UAA instance, you must ensure that the clients related to the SPs are updated with the corresponding information. Although it is possible to update a single client to interact with multiple SPs, as a best practice, you can define a new client for each of your application to interact with UAA.
    MetadataSpecify the SP metadata and download the UAA IdP metadata in this field. You must obtain the SP metadata from your SP administrator. You must supply the UAA IdP metadata to your SP administrator.
    UAA Validate SAML Metadata(Optional) Select this option for UAA to check the SP metadata for valid signature value. UAA performs this check every time a user initiates the SAML communication.
    The SP is displayed in the list of Service Providers.

Configuring UAA as an Identity Provider Using Scripts

As an optional procedure, you can use the configuration scripts instead of UAA Dashboard to configure UAA as Identity Provider.

Before You Begin

  • Download the following script from GitHub.
    • create-saml-sp.sh

About This Task

You can configure UAA as SAML identity provider to integrate with other service providers.

Procedure

  1. Specify your UAA instance as the intended target.
    uaac target <uaa_instance_url>

    <uaa_instance_url> is the URL to your trusted issuer, for example, https://11fa0273-9e2a-37e2-9d06-2c95a1f4f5ea.predix-uaa.run.aws-usw02-pr.ice.predix.io. You can retrieve this URL from the VCAP_SERVICES environment variable after binding your UAA instance to an application.

  2. Log in using the administrative client.
    uaac token client get admin
  3. Specify the administrative client secret at the prompt.
  4. Export Identity Provider (IdP) metadata from UAA. Provide this metadata to your Service Provider (SP) administrator so it can be imported into the SP application.

    The uaa_idp_metadata.xml file is the IdP metadata generated by your UAA instance. It is available at the following endpoint:

    <uaa_instance_url>/saml/idp/metadata

    For example,

    https://13fa0384-9e2a-48e2-9d06-2c95a1f4f5ea.predix-uaa.run.aws-usw02-pr.ice.predix.io/saml/idp/metadata
  5. Import the UAA IdP metadata into your SP application.
    This step depends on the type of service provider you use. For more information, refer to the documentation for your service provider.
  6. Provision a user for UAA IdP.
    uaac target <UAA_IDP_INSTANCE_URL>
uaac token client get admin
client secret: <admin client secret>
uaac user add <user-name> --given_name <first-name> --family_name <last-name> --emails <email> -p <password>
uaac group add zones.uaa.admin
uaac member add zones.uaa.admin <user-name>
  7. Add Service Provider configuration to UAA IdP.
    1. Obtain an access token. The client that you use to obtain access token must have the sps.write scope.

      You are redirected to UAA IdP login page. Enter credentials for user provisioned in step 3.

      For more information on obtaining access tokens, see Using UAA to Obtain OAuth2 Access Tokens.

    2. Use the create-saml-sp.sh script to add the SP configuration.
      ./create-saml-sp.sh -n <uaa-sp-name> -m uaa-sp-metadata.xml -i
  8. Check that the SP configuration was successfully added.
    uaac curl /saml/service-providers