Typically in SAML, the authentication request and assertion data is sent through the browser (http POST or http REDIRECT binding).
However, in some cases you may not want to expose the entire message to the browser. In this case, the message contents are replaced by an artifact reference, that can be requested from the artifact endpoint (backchannel).
Both the Authentication Request and the Assertion can be sent using the Artifact binding.
Note: TrustBuilder.io (acting as Service Provider) currently only supports getting the Assertion via the artifact binding.
Other use cases are not supported:
Acting as Service Provider: sending the Authentication Request with an Artifact Binding
Acting as Identity Provider: receiving the Authentication Request with an Artifact Binding
Acting as Identity Provider: sending the Assertion with an Artifact Binding
There are no strong indications that the artifact binding is more or less secure than the post/redirect binding. Because artifact bindings add complexity and additional points of failure, it's not our recommended default approach for a SAML integration.
However there are several reasons why Artifact binding would be preferred:
Technical restrictions (eg. to reduce the size of the message)
Encryption is not practical or desirable (as this is more CPU intensive)
Reluctance to expose the message contents to the browser
Because we currently only support getting the assertion via the artifact binding, there is only a practical need for the IDP to present the artifact endpoint on a TLS secured endpoint.
Although the SAML specification does not mandate how to secure the Artifact binding, we suggest Two-SSL as a recommendation:
The client (SP) should present its certificate to artifact resolution endpoint, to avoid unauthorized parties to access the Artifact Resolution Endpoint.
The Identity Provider provides the artifact response, which is signed with its own certificate to prove the authenticity.
Additional measures may include that the artifact can only be resolved once, and that it remains available for only a limited amount of time (ie. several minutes).
An IDP Push is an Identity Provider initiated Single Sign-On.
Where the normal authentication flow is initiated by an Authentication Request from the Service Provider, this is the opposite. The authentication starts by the Identity Provider, who provides an Assertion.
The assertion may or may not contain a relayState or redirect_uri (the Service Provider to which the assertion is to be presented).
When TrustBuilder.io receives an IDP-initiated assertion and it does not contain a relayState/redirect_uri and cannot be linked to an SP request, the user will be directed to the Application Catalog.
This is an endpoint that can be used to trigger an "IDP push" from TrustBuilder.io to a SAML Service Provider.
It is possible that the
relayState parameter is used to indicate to the SAML SP what URL the user has to be redirected.
OpenIDConnect Error Codes
OAuth Token Exchange
The Token Exchange process is an extension on the OAuth 2.0 protocol, as described in the following draft specification: https://tools.ietf.org/html/draft-ietf-oauth-token-exchange-19
It allows a Client to access multiple resources with a single access token, by exchanging it at TrustBuilder.io for access tokens that have, for instance, a reduced scope. It has the following two major use cases:
Impersonation → A client is impersonating a principal, to gain access to its resources. The impersonating client has all the rights of the principal it's impersonating.
Delegation → A principal is acting as a delegate of another principal to access its resources. It retains its own rights, and the resource is aware that this client is acting on behalf of a different client.
This mode is currently not supported by TrustBuilder.io.
TrustBuilder.io can accept access tokens, or SAML assertions from any known IDP, and exchange them for an access token to a specific resource (issued by TrustBuilder). This can dramatically simplify the implementation on the side of the resource; as it only needs to integrate with a single IDP. Which makes this a very useful implementation for a Microservices architecture, as an external access token can be exchanged for an internal token.
When to use Token Exchange?
There are scenarios when a Client accesses a resource server, which in turn needs to access resources hosted by other downstream services.
The Client sends in the access token that it received to TrustBuilder.io, which acts as a Security Token Service (STS). TrustBuilder.io will exchange the token provided by the Client with a token that can be used by the downstream service (Configured as an OAuth SP in TrustBuilder.io). This new token may have a reduced scope or expiration timestamp.
This setup is particularly useful in an architecture where lots of independent services exist, which each have their own OAuth Client ID. It allows all business and authorization logic to be concentrated in a single entity, and a single access token issuer can be used throughout the service landscape, greatly improving user experience.
The following flowchart explains the internal logic TrustBuilder.io uses to validate a request under the Token Exchange grant.
Which IDP's are trusted? If the IDP is trusted, the token is validated based on the IDP's configuration (which must be set in TrustBuilder.io)
Has the user given consent?
If the downstream service accesses information of the user which requires content, TrustBuilder.io will verify that this consent exists (for this combination of Scope, User and Service Provider).
The token exchange will never request a user to grant consent, so the consent must already exist or be provided out of band.
Additional business logic via workflows
Using Token Exchange with a Workflow IDP
TrustBuilder.io workflows (i.e. Internal IDP's) can be used as Identity Providers for a Token Exchange grant, as long as they provide a token which can be validated.
The IDP workflow also requires support for validating one of its own dispensed tokens.
Scopes provide a way to limit the amount of access that is granted to an access token.
They are used both in OAuth2 and OpenIDConnect. However, OpenIDConnect extends the usage of scopes.
Scopes can be authorized by a user. This is typically requested at the point the user logs in, as shown below.
A scope is requested by a Service Provider. It is authorized by a user, who is authenticated by an Identity Provider.
Though not every request is necessarily authorized by a user (eg. in a machine-to-machine context). But Scopes are still used in this case.
OAuth2 vs OpenIDConnect
You can implement your API's to enforce a restriction of a combination of scopes. So, when a client receives a token that has "READ" scope, and it uses this token to call an API endpoint that requires "WRITE" access, the call will fail.
OAuth scopes are defined as a list of names in the metadata.
OAuth scopes are applied on the API Service Providers in TrustBuilder.io. There you define which scope(s) are allowed to access certain API locations and methods.
OpenIDConnect in an extension to OAuth2, so the principles covered by OAuth2 still apply. But in addition, A Service Provider can request additional user information (=claims) from the IDP (provided in an ID Token, in addition to an Access Token).
Pre-defined sets of Claims can be requested using specific scope values. Although not currently supported by TrustBuilder.io, individual Claims can also be requested using the claims request parameter.
A scope called 'openid' MUST be included in an Authorization request, to make it as an OpenIDConnect request. Otherwise, the request will be made as an OAuth2 request.