Glossary of Terms for SAML

Includes definitions for common terms used in the Akana API Platform SAML documentation.

assertion

See SAML assertion.

Assertion Consumer Service (ACS) endpoint

The endpoint where the Service Provider will receive SAML assertions issued by the Identity Provider (<Response> message if HTTP POST is used artifact if HTTP Artifact is used).

Artifact

See SAML Artifact.

Artifact Resolution Service (ARS)

A service that you must set up if you want to use the HTTP Artifact binding (supported only for single sign-on SAML response messages). In a response message scenario, the ARS is on the Identity Provider side. You can then use the service to retrieve the full message using the artifact. See HTTP Artifact.

attributes

One or more values you will use to identify your users with the Identity Provider. For example, you might use attributes of firstname, lastname, and emailaddress, or you might use attributes of username and password.

base URL

The base URL for your implementation: {protocol_scheme}://{host}:{port}. It must be the container address of the container where the SAML Web SSO feature is initialized and where the OAuth Provider feature is running (container or cluster URL). The platform uses this to construct the default endpoint, used for error responses.

Some Identity Providers, if an error is encountered, send the error message to the default URL specified in the Service Provider metadata file, rather than to the specific URL at which the error was encountered. For example, if there are two URLs in the file, one for platform login and the second for an OAuth Provider domain, an error message relating to the OAuth Provider domain would be sent to the platform login endpoint. PingFederate is an example of an Identity Provider that returns an error response in this way.

To get around this, the platform constructs a default endpoint to be use for error responses, using the base URL for your implementation.

For example, if the base URL is http://www.acmepaymentscorp, the platform would construct the following default endpoint: http://www.acmepaymentscorp/api/login/ssoLogin. This would show as the first md:AssertionConsumerService entry in the exported Service Provider metadata file generated when you configure the identity system entry in Policy Manager.

To view an example, see the sample Service Provider metadata file: Sample Metadata File: Service Provider.

Entity ID

A unique identifier for a SAML entity. A SAML entity can be a Service Provider or an Identity Provider.

As a Service Provider, you define your Entity ID. When setting up your account with the Identity Provider, you must specify the Entity ID, which must be unique within the IdP so that the IdP can identify your Service Provider.

The Entity ID is used as the value of the <Issuer> element inside the SAML protocol message. In an authentication request, the <Issuer> element contains the Entity ID of the Service Provider; in the SAML response, it contains the Entity ID of the Identity Provider.

From the perspective of the Service Provider, the Entity ID is analogous to the client_id in OAuth.

HTTP Artifact

One of the binding options supported by the SAML protocol. HTTP Artifact is useful in scenarios where the SAML requester and responder are using an HTTP User-Agent and do not want to transmit the entire message, either for technical or security reasons. Instead, a SAML Artifact is sent, which is a unique ID for the full information. The IdP can then use the Artifact to retrieve the full information. The artifact issuer must maintain state while the artifact is pending. An Artifact Resolution Service (ARS) must be set up.

HTTP Artifact sends the artifact as a query parameter.

Community Manager currently supports this binding option for SAML responses, but not for SAML requests.

HTTP POST

One of the binding options supported by the SAML protocol.

HTTP POST sends the message content as a POST parameter, in the payload.

Community Manager currently supports this binding option for SAML, for both requests and responses.

HTTP Redirect

One of the binding options supported by the SAML protocol.

When HTTP Redirect is used, the Service Provider redirects the user to the Identity Provider where the login happens, and the Identity Provider redirects the user back to the Service Provider. HTTP Redirect requires intervention by the User-Agent (the browser).

HTTP Redirect sends the message content in the URL. Because of this, it cannot be used for the SAML response, because the size of the response will typically exceed the URL length allowed by most browsers.

Community Manager currently supports this binding option for SAML requests.

Identity Provider

In terms of SAML, the Identity Provider is the entity that verifies the identity of the user, in response to a request by the Service Provider.

The Identity Provider is responsible for maintaining and authenticating the user's identity. In terms of platform usage, the Identity Provider verifies by means of user credentials such as username and password.

IdP

Abbreviation for Identity Provider.

PingFederate

A third-party company that provides SAML Identity Provider services, verifying the identity of users for Service Providers using the SAML Web SSO protocol. The CM SAML solution is tested with the PingFederate product.

For more information about PingFederate, see https://www.pingidentity.com.

SAML

Acronym for Security Assertion Markup Language. SAML is an identity federation standard that enables single sign-on. It is an XML-based standard for exchanging authentication and authorization data between a Service Provider (providing a service to the user) and an Identity Provider (providing user identity verification for the Service Provider).

SAML Artifact

When the HTTP Artifact binding is used, the Artifact is a unique ID used by the Service Provider (SP) and Identity Provider (IdP) to reference a specific user session or transaction. The SP can use the Artifact to query the IdP for information about the user.

SAML assertion

A SAML assertion is an XML document returned by the Identity Provider to the Service Provider after authentication of the user. The assertion has a very specific structure, as defined by the SAML standard. A SAML assertion has a <Subject> element which contains information about the user. It might have conditions and attributes associated with the information being conveyed. It is digitally signed and asserts that the user has been authenticated. For an example, see Sample Assertion.

Note: the above definition applies to an authentication assertion, which applies in the context of the platform's support of SAML. There are other types of SAML assertions.

SAML Web SSO

Single sign-on over the Web using the SAML Web Browser SSO Profile. For references to the SAML standard for this profile, see SAML specifications.

Service Provider

In terms of SAML, the Service Provider (SP) offers a service to the user and allows the user to sign in by using SAML. When the user attempts to sign in, the SP sends a SAML authentication request to the Identity Provider (IdP). The IdP validates the request, authenticates the user, and creates a SAML assertion that represents the user's identity and, in some cases, sends additional information about the user in the form of associated attributes. The SAML assertion is digitally signed and encrypted and then sent back to the Service Provider that initiated the request.

Identity federation software at the SP receives the assertion, verified the authenticity, decrypts, and shares the information with the application, which then logs in the user.

SSO

Abbreviation for single sign-on, a feature allowing a user to sign in once for more than one system rather than signing in separately to each system.

If an application offers single sign-on, this means that the application, acting as a Service Provider (providing services to an end user) uses an Identity Provider, an entity that provides authentication and possibly authorization services, to verify the identity of an end user logging on to the app. The user signs in to the Service Provider, and the Service Provider either implicitly or explicitly requests authentication from the Identity Provider. Once authentication is received, the Service Provider delivers the requested service to the end user.

SSO Circle

A third-party company that provides SAML Identity Provider services, verifying the identity of users for Service Providers using the SAML Web SSO protocol.

The CM SAML solution is tested with the SSOCircle SAML Identity Provider. For more information, see http://www.ssocircle.com.

SP

Abbreviation for Service Provider.

Related Topics