...
To configure security, see Security.
Obtaining an Access Token
...
| Code Block |
|---|
GET <base-auth-url>/token
|
The <base-auth-url> can be found either by making a request and retrieving the authentication URI (auth_uri) in the response body or by knowing the configuration of the CDAP server for the security.auth.server.announce.address and port, as described in Security.
The required header and request parameters may vary according to the external authentication mechanism that has been configured. For username and password based mechanisms, the Authorization header may be used:
| Code Block |
|---|
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW |
HTTP Responses
Status Codes | Description |
|---|---|
| Authentication was successful and an access token will be returned |
| Authentication failed |
Success Response Fields
Response Fields | Description |
|---|---|
| The Access Token issued for the client. The serialized token contents are base-64 encoded for safe transport over HTTP. |
| In order to conform with the OAuth 2.0 Bearer Token Usage specification (RFC 6750), this value must be "Bearer". |
| Token validity lifetime in seconds. |
Example
Sample request:
| Code Block |
|---|
GET <base-auth-url>/token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
|
Sample response:
| Code Block |
|---|
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"Bearer",
"expires_in":3600,
}
|
Comments
Only
Bearertokens (RFC 6750) are currently supported
...
| Code Block |
|---|
GET <base-url>/<resource> HTTP/1.1
|
The <base-url> is typically http://<host>:11015 or https://<host>:10443, as described in the Microservices Conventions.
In order to authenticate, all client requests must supply the Authorization header:
| Code Block |
|---|
Authorization: Bearer wohng8Xae7thahfohshahphaeNeeM5ie
|
For CDAP-issued access tokens, the authentication scheme must always be Bearer.
HTTP Responses
Status Codes | Description |
|---|---|
| Authentication was successful and an access token will be returned |
| Authentication failed |
| Authentication succeeded, but access to the requested resource was denied |
Error Response Fields
Response Fields | Description |
|---|---|
| An error code describing the type of failure (see Error Code Values) |
| A human readable description of the error that occurred |
| List of URIs for running authentication servers. If a client receives a |
Error Code Values
Response Fields | Description |
|---|---|
| The request is missing a required parameter or is otherwise malformed |
| The supplied access token is expired, malformed, or otherwise invalid. The client may request a new access token from the authorization server and try the call again. |
| The supplied access token was valid, but the authenticated identity failed authorization for the requested resource |
Example
A sample request and responses for different error conditions are shown below. Header values are wrapped for display purposes.
...
| Code Block |
|---|
GET <base-url>/resource HTTP/1.1
Host: server.example.com
Authorization: Bearer wohng8Xae7thahfohshahphaeNeeM5ie
|
Missing token:
| Code Block |
|---|
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example"
{
"auth_uri": ["https://server.example.com:10010/token"]
}
|
Invalid or expired token:
| Code Block |
|---|
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="example",
error="invalid_token",
error_description="The access token expired"
{
"error": "invalid_token",
"error_description": "The access token expired",
"auth_uri": ["https://server.example.com:10010/token"]
}
|
Comments
The
auth_urivalue in the error responses indicates where the authentication server(s) are running, allowing clients to discover instances from which they can obtain access tokens.