Initiates the sign-in process with the given identity provider
GET /security/authentication/identityProviders/{identityProvider}/signin
The response depends on the type of identity provider.
For providers implementing the OAuth 2.0 or the OpenID Connect protocol:
Section titled “For providers implementing the OAuth 2.0 or the OpenID Connect protocol:”Usually, client application would have to follow the identity providers mechanisms for obtaining a Json Web Token (JWT) and then send that token on each subsequent request.
This is not ideal in some scenarios such as public applications that run in browsers where keeping the token secure is challenging. In addition, the application has to attach the token to each request causing additional development overhead.
In these cases, a commonly applied mechanism is to have the identity provider send the token to the back-end service for storage. The service then issues a cookie to the client associating all subsequent requests with the token. This way, the token is not stored in the web application and the cookie is automatically sent along with every request automatically by the browser. Another benefit of this is that the service is able to refresh the token on it’s own (given that the identity provider supports refresh tokens), reducing the need for the client/user to reauthenticate. In summary, accessing this endpoint essentially creates an authenticated session between the client and the service. Note that after the initial requests, the client is initially redirected to the identity provider for authorization. The identity provider it self may then initiate a series of redirects to complete the process.
For other providers:
Section titled “For other providers:”The response usually would be a standard HTTP authentication challenge, indicated by a 401 (Unauthorized) response in conjunction with a WWW-Authenticate header describing the supported types of credentials.
Some of these challenges may cause the client application (i.e. a browser) to prompt the user for credentials. Some may not, requiring the client application to take appropriate action (such as acquiring and providing a token, etc.)
Examples:
- For identity providers requiring username/password identification, the header may contain the value
BasicorDigestprompting the browser to ask the user for these credentials. - For providers only supporting JWTs, the value of the header would be
Bearer. - For Windows authentication, the value would be ’Negotiate
orNtlm`
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
identityProvider |
path | string |
yes | The name of the identity provider to sign in with. |
referrer |
query | string (uri) |
no | The relative path to redirect to after the client has been signed in successfully. |
Responses
Section titled “Responses”| Code | Description | Type |
|---|---|---|
302 |
After successful sign-in with an OpenID Connect provider (which may require several intermediate redirects) , the client is redirected to the absolute URI or relative path given in the referrer parameter. |
any |
401 |
This response indicates that an HTTP authentication challenge was issued. | ProblemDetails |
404 |
This response indicates that no identity provider is configured under the given name. | ProblemDetails |
4XX |
Indicates that the request failed due to a client error. Please refer to the details provided in the body of the response in order to ensure that the request can be handled properly. | ProblemDetails |
5XX |
Indicates that the request failed due to an error that occurred on the server. Consider reporting this error to the server operators. | ProblemDetails |
Headers
| Header | Type | Description |
|---|---|---|
Location |
any |
The location to which the client should be returned to after sign-in. |
Set-Cookie |
any |
If sign-in was successful, this header contains the cookie identifying the session. |
Headers
| Header | Type | Description |
|---|---|---|
WWW-Authenticate |
any |
The HTTP authentication scheme(s) supported for authentication. |
Schema: ProblemDetails
{ "type": "?", "title": "HK09008", "status": 400, "detail": "A description of the problem", "instance": "https://..", "root": { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, "roots": [ { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." } ], "traceId": "dd71e2e0-c77a-4608-b1d7-fcb9353b9a35"}Schema: ProblemDetails
{ "type": "?", "title": "HK09008", "status": 400, "detail": "A description of the problem", "instance": "https://..", "root": { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, "roots": [ { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." } ], "traceId": "dd71e2e0-c77a-4608-b1d7-fcb9353b9a35"}Schema: ProblemDetails
{ "type": "?", "title": "HK09008", "status": 400, "detail": "A description of the problem", "instance": "https://..", "root": { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, "roots": [ { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." } ], "traceId": "dd71e2e0-c77a-4608-b1d7-fcb9353b9a35"}Schema: ProblemDetails
{ "type": "?", "title": "HK09008", "status": 400, "detail": "A description of the problem", "instance": "https://..", "root": { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, "roots": [ { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." } ], "traceId": "dd71e2e0-c77a-4608-b1d7-fcb9353b9a35"}Schema: ProblemDetails
{ "type": "?", "title": "HK09008", "status": 400, "detail": "A description of the problem", "instance": "https://..", "root": { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, "roots": [ { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." } ], "traceId": "dd71e2e0-c77a-4608-b1d7-fcb9353b9a35"}Schema: ProblemDetails
{ "type": "?", "title": "HK09008", "status": 400, "detail": "A description of the problem", "instance": "https://..", "root": { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, "roots": [ { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." } ], "traceId": "dd71e2e0-c77a-4608-b1d7-fcb9353b9a35"}Schema: ProblemDetails
{ "type": "?", "title": "HK09008", "status": 400, "detail": "A description of the problem", "instance": "https://..", "root": { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, "roots": [ { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." } ], "traceId": "dd71e2e0-c77a-4608-b1d7-fcb9353b9a35"}Schema: ProblemDetails
{ "type": "?", "title": "HK09008", "status": 400, "detail": "A description of the problem", "instance": "https://..", "root": { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, "roots": [ { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." }, { "type": "?", "title": "HK15019", "status": 500, "detail": "An error occurred while performing the requested operation...", "instance": "https://.." } ], "traceId": "dd71e2e0-c77a-4608-b1d7-fcb9353b9a35"}