diff --git a/api-ref/source/v3-ext/federation.inc b/api-ref/source/v3-ext/federation.inc index 7ffc63ed25..82e30873c4 100644 --- a/api-ref/source/v3-ext/federation.inc +++ b/api-ref/source/v3-ext/federation.inc @@ -302,88 +302,7 @@ to ``ss:mem:``. .. include:: federation/projects-domains/projects-domains.inc - -.. TODO(samueldmq): This is the Federation Authentication API, move it to its - own file. - -Request an unscoped OS-FEDERATION token -======================================= - -.. rest_method:: GET /v3/OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth - -A federated ephemeral user may request an unscoped token, which can be used to -get a scoped token. - -If the user is mapped directly (mapped to an existing user), a standard, -unscoped token will be issued. - -Due to the fact that this part of authentication is strictly connected with the -SAML2 authentication workflow, a client should not send any data, as the -content may be lost when a client is being redirected between Service Provider -and Identity Provider. Both HTTP methods - GET and POST should be allowed as -Web Single Sign-On (WebSSO) and Enhanced Client Proxy (ECP) mechanisms have -different authentication workflows and use different HTTP methods while -accessing protected endpoints. - -The returned token will contain information about the groups to which the -federated user belongs. - -Example Identity API token response: `Various OpenStack token responses -`__ - -Response Example ----------------- - -.. literalinclude:: ./samples/OS-FEDERATION/unscoped-token-response.json - :language: javascript - - -Request a scoped OS-FEDERATION token -==================================== - -.. rest_method:: POST /v3/auth/tokens - -A federated user may request a scoped token, by using the unscoped token. A -project or domain may be specified by either id or name. An id is sufficient to -uniquely identify a project or domain. - -Request Example ---------------- - -.. literalinclude:: ./samples/OS-FEDERATION/scoped-token-request.json - :language: javascript - -Similarly to the returned unscoped token, the returned scoped token will have -an ``OS-FEDERATION`` section added to the ``user`` portion of the token. - -Response Example ----------------- - -.. literalinclude:: ./samples/OS-FEDERATION/scoped-token-response.json - :language: javascript - - -Web Single Sign On authentication (New in version 1.2) -====================================================== - -.. rest_method:: GET /v3/auth/OS-FEDERATION/websso/{protocol}?origin=https%3A//horizon.example.com - -For Web Single Sign On (WebSSO) authentication, users are expected to enter -another URL endpoint. Upon successful authentication, instead of issuing a -standard unscoped token, keystone will issue JavaScript code that redirects -the web browser to the originating Horizon. An unscoped federated token will -be included in the form being sent. - - -Web Single Sign On authentication (New in version 1.3) -====================================================== - -.. rest_method:: GET /v3/auth/OS-FEDERATION/identity_providers/{idp_id}/protocol/{protocol_id}/websso?origin=https%3A//horizon.example.com - -In contrast to the above route, this route begins a Web Single Sign On request -that is specific to the supplied Identity Provider and Protocol. Keystone will -issue JavaScript that handles redirections in the same way as the other route. -An unscoped federated token will be included in the form being sent. +.. include:: federation/auth/auth.inc .. TODO(samueldmq): This is the Generating Assertions API, move it to its own diff --git a/api-ref/source/v3-ext/federation/auth/auth.inc b/api-ref/source/v3-ext/federation/auth/auth.inc new file mode 100644 index 0000000000..4b261efdca --- /dev/null +++ b/api-ref/source/v3-ext/federation/auth/auth.inc @@ -0,0 +1,80 @@ +.. -*- rst -*- + +Request an unscoped OS-FEDERATION token +======================================= + +.. rest_method:: GET /v3/OS-FEDERATION/identity_providers/{identity_provider}/protocols/{protocol}/auth + +A federated ephemeral user may request an unscoped token, which can be used to +get a scoped token. + +If the user is mapped directly (mapped to an existing user), a standard, +unscoped token will be issued. + +Due to the fact that this part of authentication is strictly connected with the +SAML2 authentication workflow, a client should not send any data, as the +content may be lost when a client is being redirected between Service Provider +and Identity Provider. Both HTTP methods - GET and POST should be allowed as +Web Single Sign-On (WebSSO) and Enhanced Client Proxy (ECP) mechanisms have +different authentication workflows and use different HTTP methods while +accessing protected endpoints. + +The returned token will contain information about the groups to which the +federated user belongs. + +Example Identity API token response: `Various OpenStack token responses +`__ + +Response Example +---------------- + +.. literalinclude:: federation/auth/samples/unscoped-token-response.json + :language: javascript + + +Request a scoped OS-FEDERATION token +==================================== + +.. rest_method:: POST /v3/auth/tokens + +A federated user may request a scoped token, by using the unscoped token. A +project or domain may be specified by either id or name. An id is sufficient to +uniquely identify a project or domain. + +Request Example +--------------- + +.. literalinclude:: federation/auth/samples/scoped-token-request.json + :language: javascript + +Similarly to the returned unscoped token, the returned scoped token will have +an ``OS-FEDERATION`` section added to the ``user`` portion of the token. + +Response Example +---------------- + +.. literalinclude:: federation/auth/samples/scoped-token-response.json + :language: javascript + + +Web Single Sign On authentication (New in version 1.2) +====================================================== + +.. rest_method:: GET /v3/auth/OS-FEDERATION/websso/{protocol}?origin=https%3A//horizon.example.com + +For Web Single Sign On (WebSSO) authentication, users are expected to enter +another URL endpoint. Upon successful authentication, instead of issuing a +standard unscoped token, keystone will issue JavaScript code that redirects +the web browser to the originating Horizon. An unscoped federated token will +be included in the form being sent. + + +Web Single Sign On authentication (New in version 1.3) +====================================================== + +.. rest_method:: GET /v3/auth/OS-FEDERATION/identity_providers/{idp_id}/protocol/{protocol_id}/websso?origin=https%3A//horizon.example.com + +In contrast to the above route, this route begins a Web Single Sign On request +that is specific to the supplied Identity Provider and Protocol. Keystone will +issue JavaScript that handles redirections in the same way as the other route. +An unscoped federated token will be included in the form being sent. diff --git a/api-ref/source/v3-ext/federation/auth/parameters.yaml b/api-ref/source/v3-ext/federation/auth/parameters.yaml new file mode 100644 index 0000000000..f5364194f2 --- /dev/null +++ b/api-ref/source/v3-ext/federation/auth/parameters.yaml @@ -0,0 +1,7 @@ +# variables in header + +# variables in path + +# variables in query + +# variables in body diff --git a/api-ref/source/v3-ext/samples/OS-FEDERATION/scoped-token-request.json b/api-ref/source/v3-ext/federation/auth/samples/scoped-token-request.json similarity index 100% rename from api-ref/source/v3-ext/samples/OS-FEDERATION/scoped-token-request.json rename to api-ref/source/v3-ext/federation/auth/samples/scoped-token-request.json diff --git a/api-ref/source/v3-ext/samples/OS-FEDERATION/scoped-token-response.json b/api-ref/source/v3-ext/federation/auth/samples/scoped-token-response.json similarity index 100% rename from api-ref/source/v3-ext/samples/OS-FEDERATION/scoped-token-response.json rename to api-ref/source/v3-ext/federation/auth/samples/scoped-token-response.json diff --git a/api-ref/source/v3-ext/samples/OS-FEDERATION/unscoped-token-response.json b/api-ref/source/v3-ext/federation/auth/samples/unscoped-token-response.json similarity index 100% rename from api-ref/source/v3-ext/samples/OS-FEDERATION/unscoped-token-response.json rename to api-ref/source/v3-ext/federation/auth/samples/unscoped-token-response.json