Adding a SAML Application

Create a Security Assertion Markup Language (SAML) application and grant it to users so that your users can single sign-on (SSO) into your SaaS applications that support SAML for SSO.

  1. In the Identity Cloud Service console, expand the Navigation Drawer, and then click Applications.
  2. Click Add.
  3. In the Add Application window, click SAML Application.
  4. In the App Details section of the Add SAML Application page, provide values for the following fields:
    • In the Name field, enter a name for the application.

      For applications with lengthy names, the application name appears truncated in the My Apps page. Consider keeping your application names as short as possible.

    • In the Description field, enter 250 or fewer characters to provide a description of the application.

    • Click Upload to add an icon for your application.

    • In the Application URL / Relay State field, enter a value which will be sent to the SAML SP as the SAML RelayState parameter.

    • In the Custom Login URL field, specify a custom login URL. However, if you are using a default login page provided by Oracle Identity Cloud Service, then leave this field blank.

    • In the Custom Logout URL field, specify a custom logout URL. However, if you are using a default login page provided by Oracle Identity Cloud Service, then leave this field blank.

    • In the Custom Error URL field, enter the error page URL to which a user has to be redirected, in case of a failure. This is an optional field. However, if not specified, the tenant specific Error page URL will be used. If both the error URLs are not configured, then the error will be redirected to the Oracle Identity Cloud Service Error Page (/ui/v1/error).

      When a user tries to use social authentication (ex: Google, Facebook, and so on) for logging into Oracle Identity Cloud Service, the callback URL must be configured in the Custom Error URL field. Social providers need this callback URL to call Oracle Identity Cloud Service and send the response back after social authentication. The provided callback URL is used to verify whether the user exists or not (in the case of first time social login), and display an error if the social authentication has failed.

    • In the Linking callback URL field, enter the URL that Oracle Identity Cloud Service can redirect to after linking of a user between social providers and Oracle Identity Cloud Service is complete. This is an optional field.

      When you create a custom app using Oracle Identity Cloud Service custom SDK and integrate with Oracle Identity Cloud Service Social Login, the custom app needs to have the Linking callback URL which can be redirected after linking of the user between social provider and Oracle Identity Cloud Service is complete.

    • Click Add to add App Links that are associated with the application. The Link window appears. App Links are services such as Mail or Calendar that are offered by applications such as Google or Office 365.

      In the Link window:
      1. In the Name field, enter the App Link name.

      2. In the Link field, enter the URL used to access the application.

      3. Click Upload to upload an icon.

      4. Select Visible check box if you want your application to appear automatically on each user’s My Apps page.

        Note:

        Selecting this check box does not enable or disable SSO into the application.
      5. Click Add.

      The App Link information appears in the App Details section of the application page.

      To remove an App Link, select the row, and then click Remove.

      Note:

      There is a delay (a few seconds) between clicking Remove and the App no longer appearing on the My Apps page. App Link deletion (and grants related to those App Links) is asynchronous. Wait a few seconds for the asynchronous task to remove the App and its grants before trying My Apps again.
  5. In the Tags section of the Add SAML Application page, click Add Tag to add tags to your SAML application to organize and identify it. See Adding Tags to an Application.
  6. In the Display Settings sections of the Add SAML Application page, make the following selections:
    • Select Display in My Apps check box to specify whether you want the SAML App to be listed on the My Apps page.

      When you select the Display in My Apps check box in applications, the app is then visible in the My Apps page, but selecting this check box doesn’t enable or disable SSO to the app.

      The flag to enable or disable SSO comes from the app template. Use the Oracle Identity Cloud Service REST APIs to update this flag. You cannot set the SSO flag from the UI. See REST API for Oracle Identity Cloud Service.

    • Select the User can request access check box if you want the app to be listed in the Catalog. This option allows end users to request access to the app from their My Apps page by clicking Add and then selecting the app from the Catalog.

    Note:

    Don’t forget to activate the application so that users can request access.
  7. Click Next to configure SSO details for the SAML application.
  8. In the General section of the SSO Configuration page, define the following:
    • Entity ID: Enter a globally unique name for a SAML entity. It usually takes a URL of an identity provider or a service provider as a value.

    • Assertion Consumer URL: Enter the URL to which the SAML identity provider will send the SAML assertion. This URL must begin with either the HTTP or HTTPS protocol.

    • NameID Format: Select the type of format to use for the NameID. The service provider and the identity provider use this format to easily identify a subject during their communication.

      Note:

      When you integrate Oracle Identity Cloud Service with MS SharePoint app based on WS Fed 1.1 protocol, the following options are not available in the NameID format: Persistent, Kerberos, and Transient.
    • NameID Value: Select the NameID Value to identify the user that is logged in. The available options are User Name , the user’s Primary Email address and Expression. When you select the Expression option, enter a regular expression as a value in the text box. There is no character limit for the value, however, there are validation rules that are performed on the value for any invalid characters that cannot be mapped.

    • Signing Certificate: Upload the signing certificate that is used to encrypt the SAML assertion.

      Note:

      Some browsers show file paths prepended with c:\fakepath\. This behavior is a security feature of the browser and does not disrupt the upload process.
  9. Expand Advanced Settings on the SSO Configuration page, and then use the following table to define a more fine-grained SAML configuration.
    Option Description
    Signed SSO

    Select Assertion to indicate that you want the SAML assertion signed. Select Response when you want the SAML authentication response signed.

    Include Signing Certificate in Signature

    Select the check box to include the signing certificate in the signature, for example, when the application requires that the signing certificate is sent along with the assertion.

    Signature Hashing Algorithm

    Select the type of signing algorithm that you want to use to sign the assertion or the response, either SHA-256 or SHA-1. SHA-256 generates a fixed 256-bit hash. SHA-1 generates a 160-bit hash value known as a message digest.

    Note:

    In a FIPS enabled environment, set the Signature Hashing Algorithm to SHA-256, the only supported hashing algorithm, to avoid errors during SSO.
    Enable Single Logout

    Select to configure SAML single logout. Single logout enables a user to lot out of all participating sites in a federated session almost simultaneously. This check box is selected by default. Clear it if you do not want to enable single logout.

    Logout Binding

    Select whether the log out request is sent as a REDIRECT (transported using HTTP 302 status-code response messages) or a POST (transported in HTML form-control content, which uses a base-64 format). This list box appears only if you select the Enable Single Logout check box.

    Single Logout URL

    Enter the location (HTTP or HTTPS) where the log out request is sent. This field appears only if you select the Enable Single Logout check box.

    Logout Response URL

    Enter the location (HTTP or HTTPS) where the log out response is sent. This field appears only if you select the Enable Single Logout check box.

    Encrypt Assertion

    Select if you want to encrypt the assertion, and then define the encryption algorithm that you want to use and upload the encryption certificate.

    Encryption Algorithm

    Select which encryption algorithm that you want to use to encrypt the SAML assertion. This list box appears only if you select the Encrypt Assertion check box.

    Encryption Certificate

    Click Upload to upload the encryption certificate that is used to encrypt the SAML assertion. This button appears only if you select the Encrypt Assertion check box.

  10. Expand Attribute Configuration on the SSO Configuration page to add user-specific and group-specific attributes to the SAML assertion. This is useful if your application uses user-specific or group-specific attributes, and you want to send that information as part of the SAML assertion.
  11. Click the plus sign next to Attributes, and then use the following table to specify the user attribute that you want to include. User information in the attribute statement contains a list of attributes. Each attribute includes a name and a list of values (in the case of multiple attribute values). Each value includes a value and the format of the value.
    Option Description
    Name

    Enter the name of the SAML assertion attribute.

    Format

    Select the format of this SAML assertion attribute: Basic, URI Reference, or Unspecified.

    Note:

    When you integrate Oracle Identity Cloud Service with MS SharePoint app based on WS Fed 1.1 protocol, Format drop-down is replaced with Namespace.
    Type
    Select one of the options below to specify the value of the assertion attribute.:
    • User Attribute

      Select this option to choose one of the predefined list of user attributes or group attributes in the Value drop-down as the value of the assertion attribute. In order to specify group attributes, select User Attribute and in the Value field, select Group Membership.

    • Expression/Literal

      Select this option when you cannot use any of the predefined values in the Value drop-down. You can provide an expression in the Value text box to specify the value of the SAML assertion attribute.

      In order to specify group attributes, select Expression/Literal and specify an expression to fetch the groups.

      Example: The following expression specifies that the value of the SAML attribute should be the names of all the groups to which the user belongs: $(user.groups[*].display).

    Value

    Select or enter the value to send as part of the assertion based on the Type that you have selected.

    When the type is User Attribute, you can select one of the predefined list of user attributes as the value of the assertion attribute. Select the Group Membership option in the drop-down if you want to send the users group membership as the value of the assertion attribute. The Condition and Value columns appear when you choose Group Membership.

    When the type is Expression/Literal, the value field is a text box and you can enter any path expression to specify what should be the value of the assertion attribute.

    Some examples of path expressions are listed below:
    • To send a list of literal values as the value of the assertion attribute, use ["value1", "value2", "value3"].

    • To send “home email” as the value of the assertion attribute, use $(user.emails[type eq "home"].value).

    • To send users first name concatenated with last name as the assertion attribute, use #concat($(user.name.givenName), $(user.name.familyName)).

    • To send an account attribute called SALARY as the value of the assertion attribute, use $(account.SALARY).

    • To include an attribute department from custom schema extension, use $(user.urn:ietf:params:scim:schemas:idcs:extension:custom:User:department).

    • To send a literal value as the value of assertion, use aLiteralValue.

    Condition

    Select a condition from the drop-down to filter the group memberships. This field is enabled only when you select User Attribute as Type and Group Membership as Value. The available values are: Equals, Starts with, and All Groups.

    Value

    Enter the filter value to use when filtering the group memberships.

  12. When you are creating SAML app from scratch rather than creating a preconfigured SAML app created from the App Catalog, the Authentication and Authorization section appears. The Enforce Grants as Authorization check box is selected by default. This check box enables users to access only the application that you assigned or granted access to. If the check box is selected, Oracle Identity Cloud Service can control access to the SAML application based on grants to users and groups. If the check box is not selected, any authenticated user has access to the application regardless of the assignment status.
  13. To import the Identity Cloud Service signing certificate into your application, click Download Signing Certificate to first download the certificate file in PEM format. This certificate is used by the SAML application to verify that the SAML assertion is valid.
  14. To import the Identity Cloud Service Identity Provider metadata into your application, click Download Identity Provider Metadata to first download the metadata file in XML format. The SAML application needs this information so that it can trust and process the SAML assertion that is generated by Identity Cloud Service as part of the federation process. This information includes, for example, profile and binding support, connection endpoints, and certificate information. To get the issuing Oracle Identity Cloud Service root certificate, see Obtaining the Root CA Certificate from Oracle Identity Cloud Service.
  15. Click Finish. The application is added in a deactivated state. To activate your application, see Activating Applications.