SAML consumption

Registered by Adam Young

Keystone should be able to consume SAML documents (probably 2.0 at a minimum) to provide the authorization data for a keystone token

Blueprint information

Adam Young
Needs approval
Marek Denis
Series goal:
Accepted for icehouse
Milestone target:
milestone icon 2014.1
Started by
Dolph Mathews
Completed by
Dolph Mathews

Related branches



Spec discussion at:

Full federation use case discussion here:

More information on the use case for this blueprint:
Acme doesn't use cloud (boo) but does have their own Active Directory implementation. They would like certain employees to have single-sign-on access between an internal IT management portal and the public cloud management portal. They'd also like to control employee access within their Active Directory implementation so that should the employee be terminated, they don't have to go to the public cloud vendor to revoke access.

1. Trusted Identity Provider
        SAML assertions are done on behalf of an already-authenticated identity. (When they came to keystone, keystone should not perform any additional authentication logic). So a trust needs to be established between Keystone and the issuing identity provider. This can be possibly validating the SAML signature against a key stored by domain within Keystone

2. Mapping
        When a SAML assertion comes across it contains attributes that help form the ephemeral identity and access of the user that already authenticated. It should at a minimum include username, list of roles (if any), domain_id. We can elect to store how these attributes map to keystone attributes or rely on the issuer to pre-map (which many IdPs support today ex: For this reason, and to potentially reduce scope, can we consider mapping as a separate blueprint?

3. SAML enablement
        In most implementations of this, for a domain there is still a provisioned initial user. That user can elect to "turn on SAML authentication" and provided the trusted identity provider info (host and key). In the future we may store the mapping information at this level. Multiple "back-ends" can exist... meaning that additional "local" users can be created within keystone will SAML authentication is enabled.

4. Local vs federated user
      A local user is one stored within the keystone backend. Keystone APIs (such as list user and assign group or role to user) will still work. A federated or ephemeral user exists for only a short period of time as defined by the SAML assertion. You cannot add roles or groups to them. Listing them may return something like "<email address hidden>" to help show they are federated and where to manage their access/attributes.

ayoung: you cannot addgroups to them, but roles should be acceptable. A role assignment to an ephemeral user might be strange, but there will be cases where it is required. Why specifically forbid it?

Strictly speaking this issue is under the Federated Blueprint. SAML BP should really just cover the SAML specific issues.

Gerrit topic:,topic:bp/saml-id,n,z

Addressed by:
    Support authentication via SAML 2.0 assertions

Addressed by: (abandoned)
    Add new group related function to assignment API for federation

Addressed by: (abandoned)
    List projects and domains for groups

Gerrit topic:,topic:bp/role-assignments-unified-sql,n,z


Work Items

Dependency tree

* Blueprints in grey have been implemented.