IBM Security Verify Documentation Hub

What is SAML?

Typically, when you start working at a new company, you are given a work email that you use to login to your entitled applications. The process of authentication might involve redirecting you to a web page hosted on a product like IBM Security Verify SaaS or IBM Security Verify Access, where you may be asked to perform some additional steps. For example, register additional authentication factors for MFA or consent to a terms of use, etc. The magic behind the authentication process is usually achieved with a federation protocol - SAML or OpenID Connect. This article focuses on the SAML protocol. This standard sees widespread use in large enterprises and most SaaS applications.

Security Assertion Markup Language (SAML) is an XML-based open standard for transferring identity data between two parties: the identity provider (IdP) and the service provider (SP).

Identity Provider - Performs authentication and constructs a user identity token (called a SAML assertion), signs it and optionally encrypts it, then transmits it to the SP. This token contains user attributes (like email, family name etc.) and optionally an authorization level.

Service Provider - Trusts the Identity Provider and is able to cryptographically verify the user identity token.

In the above example, IBM Security Verify is the IdP and the application is the SP.

IBM Security Verify can act as an IdP and/or an SP. In other words, you can add an external identity provider to your IBM Security Verify tenant (instead of using the native Cloud Directory) that authenticates the user. Verify trusts the IdP and is able to process the identity token, normalize it and make attribute information available to downstream applications in another SAML identity token.

Benefits of SAML Authentication

  1. Improved user experience - Users login once on the web browser and are able to access multiple applications in the lifetime of the browser.
  2. Secure method of transmitting user data - Identity token is signed by a cryptographic key and can be optionally encrypted. This makes it tamper-proof and is able to address privacy concerns. The user data is typically posted through the browser to the SP.
  3. Option to not replicate user data - Service providers do not need to store the user information because when the user authenticates again, the SAML identity token would contain what the SP needs.
  4. Broker to support multiple identity providers - IBM Security Verify offers the ability to configure multiple SAML federated identity providers to support organizations that choose to group users in different registries. For example, privileged users vs regular employees vs consumers.

How SAML works

There are two parties: the identity provider (IdP) and the service provider (SP). For the sake of clarity, let's assume the identity provider is IBM Security Verify and the service provider is JKE Portal. The Service Provider Initiated SSO flow is described below.

  • User tries to login to JKE Portal
  • JKE Portal sends a request to authenticate through the browser. This is called an Authentication Request (AuthnRequest). It is an XML document that is signed and optionally encrypted by the SP. In addition to the AuthnRequest, a RelayState variable is randomly generated and included. This is used to avoid replay attacks in the flow.
<AuthnRequest xmlns="urn:oasis:names:tc:SAML:2.0:protocol"
              xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
              Version="2.0"
              ID="_991d037ede1f9b46e8332b19b7dc203bc3d93f3bd8"
              IssueInstant="2021-02-03T15:25:50.428Z"
              Destination="https://tenant.verify.ibm.com/saml/sps/saml20ip/saml20/12345/login"
              AssertionConsumerServiceURL="https://verifyapp.mybluemix.net/assert"
              ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
              ForceAuthn="false"
              >
    <saml:Issuer>verify-app</saml:Issuer>
    <NameIDPolicy Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
                  AllowCreate="true"
                  />
    <RequestedAuthnContext Comparison="exact">
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:1.0:am:password</saml:AuthnContextClassRef>
    </RequestedAuthnContext>
</AuthnRequest>

The AuthnRequest can be sent as part of a query string parameter (called the SAML Redirect Binding) or a self-submitting HTML FORM (called the SAML Post Binding). There are other bindings available (for example, the Artifact Binding) but they are seldom used.

  • IBM Security Verify validates the AuthnRequest and verifies that the user has authenticated. If the user has not, the user is taken through a configured authentication flow, which may or may not leverage the SAML protocol.
  • IBM Security Verify builds the SAML Assertion, which contains the user's identity information. This assertion is wrapped in a XML envelope called the Authentication Response (AuthnResponse). The assertion and/or the AuthnResponse may be signed and optionally encrypted.
  • IBM Security Verify builds a self-submitting HTML FORM that posts this AuthnResponse and the RelayState (sent in the request step) to JKE Portal.
<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                Destination="https://verifyapp.mybluemix.net/assert" 
                ID="FIMRSP_68837a65-0177-1b14-a613-9a254f0f98bd" 
                InResponseTo="_991d037ede1f9b46e8332b19b7dc203bc3d93f3bd8" 
                IssueInstant="2021-02-03T15:29:43Z" Version="2.0" 
                xmlns:ds="http://www.w3.org/2000/09/xmldsig#" 
                xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
    <saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">
        https://tenant.verify.ibm.com/saml/sps/saml20ip/saml20/12345
    </saml:Issuer>
    <ds:Signature Id="uuid68837a66-0177-17db-bf45-9a254f0f98bd">
        <ds:SignedInfo>
...
  • JKE Portal validates the submitted data, extracts the relevant user information and logs the user in.

There are a few important attributes to note above.

  • ID: New generated identifier for the message
  • IssueInstant: Timestamp when the message is generated
  • InResponseTo: The identifier of the AuthnRequest that initiated the flow
  • AssertionConsumerServiceURL: Endpoint to which the SAML Response is posted by IBM Security Verify. There may be multiple allowed endpoints configured on ISV within the SAML application configuration.
  • Issuer: The SAML Entity that is issuing the message. This is used to identify the IdP/SP both on IBM Security Verify and the application.

There are other constraints that govern the validity of the message, etc.

How do you integrate your SAML partner with IBM Security Verify

IBM Security Verify can act as both an Identity Provider and a Service Provider.

πŸ’Ž

Vivek Shankar, Product Architect

Updated 7 months ago


SAML 2.0


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.