The Authorization Token Service (ZTS) API
This API has the following attributes:
| Attribute | Value |
|---|---|
| namespace | com.yahoo.auth.zts |
| version | 1 |
All ZMS API commands require that the client use a TLS certificate issued by Athenz. Services can use their Athenz Issued Service Identity certificates when communicating with ZMS.
All ZMS API commands require that the principal executing the operation to be authenticated by providing its ServiceToken as part of the request. The NToken must be passed as the value of the Athenz-Principal-Auth header in the request. If the Authority used to authenticate the user credentials does not support authorization, then the user first must obtain a NToken from ZMS server and then use that NToken in its request.
Limited number of ZTS API endpoints are authorized against the configured policy data to verify that the principal has been given the rights to make the requested change. Each request description below gives the authorization command that includes the action and resource that the ZTS Server will run the authorization check against. For example, to delete an instance from the local database we have the following authorize statement:
authorize("delete", "{domain}:instance.{instanceId}");
This indicates that the principal requesting to delete instance id host001 from athenz.ci domain must have grant rights to action "delete" for resource called "instance.host001" in domain "athenz.ci".
Access can be checked and returned as this resource.
Access is a Struct type with the following fields:
| Name | Type | Options | Description | Notes |
|---|---|---|---|---|
| granted | Bool |
OAuth2 Access Token response.
AccessTokenResponse is a Struct type with the following fields:
| Name | Type | Options | Description | Notes |
|---|---|---|---|---|
| access_token | String | Oauth2 Access token in JWT format | ||
| token_type | String | For Athenz this will always be Bearer | ||
| expires_in | Int32 | Number of seconds the access token is valid for | ||
| scope | List | List of roles the principal has access to | ||
| refresh_token | String | Not issued by Athenz | ||
| id_token | String | ID token valid for 1 hour | Returned only if openid/service-name scopes provided as part of the request |
An action (operation) name.
ActionName is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | {CompoundName} |
Used as the prefix in a signed assertion. This uniquely identifies a signing authority. i.e. ^user^
AuthorityName is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | {CompoundName} |
AWS full role name with path
AWSArnRoleName is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | ({AWSRolePath})*{AWSRoleName} |
AWS role name without the path
AWSRoleName is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | [a-zA-Z0-9-\\._=+@,]* |
AWS role path
AWSRolePath is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | ({AWSRolePathElement}/)+ |
AWS role path single element
AWSRolePathElement is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | [a-zA-Z0-9][a-zA-Z0-9-\\._]* |
AWS Temporary credentials
AWSTemporaryCredentials is a Struct type with the following fields:
| Name | Type | Options | Description | Notes |
|---|---|---|---|---|
| accessKeyId | String | |||
| secretAccessKey | String | |||
| sessionToken | String | |||
| expiration | Timestamp |
A compound name. Most names in this API are compound names.
CompoundName is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | ({SimpleName}.){SimpleName}* |
A domain name is the general qualifier prefix, as its uniqueness is managed.
DomainName is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | {CompoundName} |
An entity name is a short form of a resource name, including only the domain and entity.
EntityName is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | {CompoundName} |
A signed identity object that could be either a client certificate or just a regular NToken (depending if the request contained a csr or not).
Identity is a Struct type with the following fields:
| Name | Type | Options | Description | Notes |
|---|---|---|---|---|
| name | CompoundName | Name of the identity | ||
| certificate | String | optional | TLS Certificate | |
| caCertBundle | String | optional | CA certificate chain | |
| sshServerCert | String | optional | SSH server certificate | |
| serviceToken | SignedToken | optional | Service NToken | |
| attributes | Map<String, String> | optional | config like attributes |
A signed instance identity object that includes client certificate
InstanceIdentity is a Struct type with the following fields:
| Name | Type | Options | Description | Notes |
|---|---|---|---|---|
| provider | ServiceName | provider service name | ||
| name | ServiceName | Name of the identity | ||
| instanceId | PathElement | unique instance id | ||
| x509Certificate | String | optional | TLS Certificate | |
| x509CertificateSigner | String | optional | CA certificate chain | |
| sshCertificate | String | optional | SSH server certificate | |
| sshCertificateSigner | String | optional | SSH server certificate signer pubilc key | |
| serviceToken | SignedToken | optional | Service NToken | |
| attributes | Map<String, String> | optional | config like attributes |
A certificate refresh request.
InstanceRefreshRequest is a Struct type with the following fields:
| Name | Type | Options | Description | Notes |
|---|---|---|---|---|
| csr | String | optional | cert CSR if requesting TLS certificate | |
| expiryTime | Int32 | optional | In seconds how long certificate should be valid for | |
| keyId | String | optional | public key identifier |
Request to request an instance with ZTS and request X.509 Certificate for the service.
InstanceRegisterInformation is a Struct type with the following fields:
| Name | Type | Options | Description | Notes |
|---|---|---|---|---|
| provider | ServiceName | provider service name | e.g. athenz.aws.us-west-2 | |
| domain | DomainName | instance domain name | ||
| service | ServiceName | instance service name | ||
| attestationData | String | identity attestation data | ||
| csr | String | cert CSR if requesting TLS certificate | ||
| ssh | String | optional | ssh CSR if requesting SSH certificate | |
| token | Bool | optional | boolean flag indicating ntoken with cert |
Json Web Key.
JWK is a Struct type with the following fields:
| Name | Type | Options | Description | Notes |
|---|---|---|---|---|
| kty | String | key type | e.g. EC or RSA | |
| kid | String | key id | ||
| alg | String | key algorithm | e.g. RS256 or ES256 | |
| use | String | key usage | e.g. sig for signing or enc for encryption | |
| crv | String | EC curve name | e.g. prime256v1, P-256 | |
| x | String | EC key x value | ||
| y | String | EC key y value | ||
| n | String | RSA key modulus value | ||
| e | String | RSA key public exponent value |
Json Web Key List
JWKList is a Struct type with the following fields:
| Name | Type | Options | Description | Notes |
|---|---|---|---|---|
| keys | Array | List of JWKs |
A uri safe path element
PathElement is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | [a-zA-Z0-9-\\._~=+@$,:]* |
A shorthand for a YRN with no service or location. The 'tail' of a YRN, just the domain:entity. Note that the EntityName part is optional, that is, a domain name followed by a colon is valid resource name.
ResourceName is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | {DomainName}(:{EntityName})? |
RoleAccess is a Struct type with the following fields:
| Name | Type | Options | Description | Notes |
|---|---|---|---|---|
| roles | Array<EntityName> | list of roles principal has access to |
A role certificate request.
RoleCertificateRequest is a Struct type with the following fields:
| Name | Type | Options | Description | Notes |
|---|---|---|---|---|
| csr | String | optional | cert CSR if requesting TLS certificate | |
| expiryTime | Int32 | optional | In seconds how long certificate should be valid for |
A signed role token returned by ZTS.
RoleToken is a Struct type with the following fields:
| Name | Type | Options | Description | Notes |
|---|---|---|---|---|
| token | SignedToken | Role Token | ||
| expiryTime | Integer | Expiry Time |
A service name will generally be a unique subdomain
ServiceName is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | {CompoundName} |
A signed assertion if identity. For example: the YBY cookie value. This token will only make sense to the authority that generated it, so it is beneficial to have something in the value that is cheaply recognized to quickly reject if it belongs to another authority.
SignedToken is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | [a-zA-Z0-9\\._%=;,-]* |
| Option | Value | Notes |
|---|---|---|
| pattern | [a-zA-Z0-9_][a-zA-Z0-9_-]* |
The Y-specific URL-safe Base64 variant.
YBase64 is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | [a-zA-Z0-9\._-]+ |
YEncoded includes ybase64 chars, as well as - and %. This can represent a YBY cookie and URL-encoded values
YEncoded is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | [a-zA-Z0-9\._%--]* |
A full Resource name (YRN)
YRN is a String type with the following options:
| Option | Value | Notes |
|---|---|---|
| pattern | (yrn:({ServiceName})?:({LocationName})?:)?{ResourceName} |
- Authentication: Certificate, NToken
- Authorization: None
Check access for the specified operation/action on the specified resource for the currently authenticated user if the principal query parameter is not specified. If the principal query parameter is specified, the access check verifies if that principal has access for the specified action on the resource. This is the slow centralized access for control-plane purposes.
| Name | Type | Source | Options | Description |
|---|---|---|---|---|
| action | ActionName | path | ||
| domain | DomainName | query: domain | optional | |
| principal | EntityName | query: principal | optional | |
| resource | String | query: resource | required |
Expected:
| Code | Type |
|---|---|
| 200 OK | Access |
Exception:
| Code | Type |
|---|---|
| 400 Bad Request | ResourceError |
| 401 Unauthorized | ResourceError |
| 404 Not Found | ResourceError |
- Authentication: Certificate, NToken
- Authorization: None
Return an oauth2 access token for the specific set of roles in the namespace that the user can assume.
To request an access token from ZTS Server, the client will send a POST
request with application/x-www-form-urlencoded content-type and the request body must
contain the following parameters:
grant_type : Value MUST be set to "client_credentials"
scope : list of scopes/roles requested in the access token. The caller
can either specify to include all roles the principal has access
to in a specific domain (e.g. <domain-name>:domain) or ask for
specific roles only (e.g. <domain-name>:role.<role1>). Scopes
are separated by spaces.
To request an ID token, the scope must include 'openid' and audience
service name (e.g. <domain-name>:service.<service-name>). The domain
name in id token request match the domain name in the access token
scope.
expires_in : requested expiry time for access token in seconds
| Name | Type | Source | Options | Description |
|---|---|---|---|---|
| req | String | body | request to fetch access token (see above) |
Expected:
| Code | Type |
|---|---|
| 200 OK | AccessTokenResponse |
| 403 FORBIDDEN | Principal does not have access to any roles in this domain |
Exception:
| Code | Type |
|---|---|
| 400 Bad Request | ResourceError |
| 401 Unauthorized | ResourceError |
| 403 Forbidden | ResourceError |
| 404 Not Found | ResourceError |
- Authentication: Certificate
- Authorization: None
Perform an AWS AssumeRole of the target role and return the credentials. ZTS must have been granted the ability to assume the role in IAM, and granted the ability to ASSUME_AWS_ROLE in Athenz for this to succeed. There are two optional query parameters to specify the duration in seconds for the requested credentials and the external id. Both of these options require the role to be configured accordingly in AWS IAM.
| Name | Type | Source | Options | Description |
|---|---|---|---|---|
| domainName | DomainName | path | ||
| roleName | EntityName | path | ||
| durationSeconds | Integer | query: durationSeconds | optional | Duration in seconds - min: 900, max: 43200. Must be configured in IAM |
| externalId | String | query: externalId | optional | External ID configured in IAM for the given role |
Expected:
| Code | Type |
|---|---|
| 200 OK | Access |
Exception:
| Code | Type |
|---|---|
| 400 Bad Request | ResourceError |
| 401 Unauthorized | ResourceError |
| 403 Forbidden | ResourceError |
| 404 Not Found | ResourceError |
- Authentication: Certificate, NToken
- Authorization: None
Refresh self identity if the original identity was issued by ZTS. The token must include the original requestor's name and the server will verify that the service still has authorization to grant inception to the current service requesting to refresh its identity
| Name | Type | Source | Options | Description |
|---|---|---|---|---|
| domain | DomainName | path | ||
| service | SimpleName | path | ||
| req | InstanceRefreshRequest | body |
Expected:
| Code | Type |
|---|---|
| 200 OK | Identity |
Exception:
| Code | Type |
|---|---|
| 400 Bad Request | ResourceError |
| 401 Unauthorized | ResourceError |
| 403 Forbidden | ResourceError |
| 404 Not Found | ResourceError |
- Authentication: Certificate
- Authorization: authorize("delete", "{domain}:instance.{instanceId}");
Delete the specified instance and no longer allow certificate refresh.
| Name | Type | Source | Options | Description |
|---|---|---|---|---|
| provider | ServiceName | path | ||
| service | SimpleName | path | ||
| instanceId | PathElement | path | unique instance id in provider's namespace |
Expected:
| Code | Type |
|---|---|
| 204 |
Exception:
| Code | Type |
|---|---|
| 400 Bad Request | ResourceError |
| 401 Unauthorized | ResourceError |
| 403 Forbidden | ResourceError |
| 404 Not Found | ResourceError |
| 500 Internal Server Error | ResourceError |
- Authentication: Certificate
- Authorization: None
Refresh the current certificate for this instance.
| Name | Type | Source | Options | Description |
|---|---|---|---|---|
| provider | ServiceName | path | ||
| service | SimpleName | path | ||
| instanceId | PathElement | path | unique instance id in provider's namespace | |
| info | InstanceRefreshInformation | body |
Expected:
| Code | Type |
|---|---|
| 200 OK | InstanceIdentity |
Exception:
| Code | Type |
|---|---|
| 400 Bad Request | ResourceError |
| 401 Unauthorized | ResourceError |
| 403 Forbidden | ResourceError |
| 404 Not Found | ResourceError |
| 500 Internal Server Error | ResourceError |
- Authentication: None
- Authorization: None
Register the instance for a given provider and return x.509 certificate for the service to identity itself against other Athenz enabled services.
Expected:
| Code | Type |
|---|---|
| 201 CREATED | InstanceIdentity |
Exception:
| Code | Type |
|---|---|
| 400 Bad Request | ResourceError |
| 401 Unauthorized | ResourceError |
| 403 Forbidden | ResourceError |
| 404 Not Found | ResourceError |
| 500 Internal Server Error | ResourceError |
- Authentication: Certificate,NToken
- Authorization: None
Returns list of Json Web Keys (JWKs) that can be used by the ZTS Server to sign OAuth2 Access/Id Tokens. If the optional rfc=true query argument is specified, then we return the EC key curve names strictly based on the JWK RFC - e.g. P-256.
| Name | Type | Source | Options | Description |
|---|---|---|---|---|
| rfc | Boolean | query: rfc | optional | if true then use rfc defined curve names - e.g. P-256 |
Expected:
| Code | Type |
|---|---|
| 200 OK | JWKList |
Exception:
| Code | Type |
|---|---|
| 400 Bad Request | ResourceError |
| 401 Unauthorized | ResourceError |
- Authentication: Certificate, NToken
- Authorization: None
List the roles that the given principal has in the domain.
| Name | Type | Source | Options | Description |
|---|---|---|---|---|
| domainName | DomainName | path | ||
| principal | EntityName | path |
Expected:
| Code | Type |
|---|---|
| 200 OK | RoleAccess |
Exception:
| Code | Type |
|---|---|
| 400 Bad Request | ResourceError |
| 401 Unauthorized | ResourceError |
| 403 Forbidden | ResourceError |
| 404 Not Found | ResourceError |
- Authentication: Certificate
- Authorization: None
Return a TLS certificate for the specific role in the namespace that the principal can assume. Role certificates are valid for 30 days by default.
| Name | Type | Source | Options | Description |
|---|---|---|---|---|
| domainName | DomainName | path | ||
| roleName | EntityName | path | ||
| req | RoleCertificateRequest | body | csr request |
Expected:
| Code | Type |
|---|---|
| 200 OK | RoleToken |
| 403 FORBIDDEN | Principal does not have access to any roles in this domain |
Exception:
| Code | Type |
|---|---|
| 400 Bad Request | ResourceError |
| 401 Unauthorized | ResourceError |
| 403 Forbidden | ResourceError |
| 404 Not Found | ResourceError |
- Authentication: Certificate, NToken
- Authorization: None
Check whether or not the given principal is included in the given role in the specified domain.
| Name | Type | Source | Options | Description |
|---|---|---|---|---|
| domainName | DomainName | path | ||
| roleName | EntityName | path | ||
| principal | EntityName | path |
Expected:
| Code | Type |
|---|---|
| 200 OK | Access |
Exception:
| Code | Type |
|---|---|
| 400 Bad Request | ResourceError |
| 401 Unauthorized | ResourceError |
| 403 Forbidden | ResourceError |
| 404 Not Found | ResourceError |
- Authentication: Certificate, NToken
- Authorization: None
Return a security token for the specific set of roles in the namespace that the user can assume. If the role query element is omitted, then all roles in the namespace that the authenticated user can assume are returned. The caller can specify how long the RoleToken should be valid for by specifying the minExpiryTime and maxExpiryTime parameters. The minExpiryTime specifies that the returned RoleToken must be at least valid (min/lower bound) for specified number of seconds, while maxExpiryTime specifies that the RoleToken must be at most valid (max/upper bound) for specified number of seconds. If both values are the same, the server must return a RoleToken for that many seconds. If no values are specified, the server's default RoleToken Timeout value is used.
| Name | Type | Source | Options | Description |
|---|---|---|---|---|
| domainName | DomainName | path | ||
| role | EntityList | query: role | optional | comma separated list of roles |
| minExpiryTime | Integer | query: minExpiryTime | optional | |
| maxExpiryTime | Integer | query: maxExpiryTime | optional | |
| proxyForPrincipal | EntityName | query: proxyForPrincipal | optional | request is proxy for this principal |
Expected:
| Code | Type |
|---|---|
| 200 OK | RoleToken |
| 403 FORBIDDEN | Principal does not have access to any roles in this domain |
Exception:
| Code | Type |
|---|---|
| 400 Bad Request | ResourceError |
| 401 Unauthorized | ResourceError |
| 403 Forbidden | ResourceError |
| 404 Not Found | ResourceError |