Response from Authlete's /api/auth/introspection API.
More...
Properties | |
| IntrospectionAction | Action [get, set] |
| The next action that the resource server should take. More... | |
| long | ClientId [get, set] |
| The client ID of the client application to which the access token has been issued. More... | |
| string | Subject [get, set] |
| The subject (= unique identifier) of the end-user (= resource owner) who allowed the authorization server to issue the access token to the client application. More... | |
| string[] | Scopes [get, set] |
| Scopes that are associated with the access token. More... | |
| bool | IsExistent [get, set] |
| The flag which indicates whether the access token exists or not. More... | |
| bool | IsUsable [get, set] |
| The flag which indicates whether the access token is usable (= exists and has not expired). More... | |
| bool | IsSufficient [get, set] |
| The flag which indicates whether the access token covers the required scopes. More... | |
| bool | IsRefreshable [get, set] |
The flag which indicates whether the access token can be refreshed using the associated refresh token. Even if there exists a refresh token associated with the access token, this property returns false if the refresh token has already expired. More... | |
| string | ResponseContent [get, set] |
| The response content which can be used as a part of the response to the client application. More... | |
| long | ExpiresAt [get, set] |
| The time at which the access token will expire. The value is represented as milliseconds since the Unix epoch (1970-Jan-1). More... | |
| bool | IsActive [get, set] |
The flag which indicates whether the access token is active (= exists and has not expired). This property is just an alias of the IsUsable property. The reason this property was added is to mitigate confusion that those who are familiar with RFC 7662 (OAuth 2.0 Token Introspection) may have. More... | |
| Property[] | Properties [get, set] |
| Arbitrary properties associated with the access token. More... | |
| string | ClientIdAlias [get, set] |
| The client ID alias when the authorization request or the token request for the access token was made. Note that this value may be different from the current client ID alias. More... | |
| bool | IsClientIdAliasUsed [get, set] |
| The flag which indicates whether the client ID alias was sed when the authorization request or the token request for the access token was made. More... | |
| string | CertificateThumbprint [get, set] |
| The thumbprint of the client certificate which is associated with the access token. More... | |
| string[] | Resources [get, set] |
The target resources. This represents the resources specified by the resource request parameters or by the resource property in the request object. See RFC 8707 (Resource Indicators for OAuth 2.0) for details. More... | |
| string[] | AccessTokenResources [get, set] |
| The target resources of the access token. More... | |
 Properties inherited from ApiResponse | |
| string | ResultCode [get, set] |
The code of the result of an Authlete API call. For example, "A004001". More... | |
| string | ResultMessage [get, set] |
| The message of the result of an Authlete API call. For example, "[A001202] /client/get/list,
Authorization header is missing." More... | |
Detailed Description
Response from Authlete's /api/auth/introspection API.
Authlete's /api/auth/introspection API returns JSON which can be mapped to this class. The resource server should retrieve the value of the "action" response parameter from the response and take the following steps according to the value.
When the value of the Action property is IntrospectionAction.INTERNAL_SERVER_ERROR, it means that the request from the resource server was wrong or that an error occurred in Authlete. In either case, from a viewpoint of the client application, it is an error on the server side. Therefore, the resource server should generate a response to the client application with the HTTP status of "500 Internal Server Error".
In this case, the ResponseContent property returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the resource server wants to return an error response to the client application in the way that complies with RFC 6750, the string returned from the ResponseContent property can be used as the value of the WWW-Authenticate header. The following is an example response which complies with RFC 6750.
When the value of the Action property is IntrospectionAction.BAD_REQUEST, it means that the request from the client application does not contain an access token (= the request from the resource server to Authlete does not contain the "token" request parameter).
In this case, the ResponseContent property returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the resource server wants to return an error response to the client application in the way that complies with RFC 6750, the string returned from the ResponseContent property can be used as the value of the WWW-Authenticate header. The following is an example response which complies with RFC 6750.
When the value of the Action property is IntrospectionAction.UNAUTHORIZED, it means that the access token does not exist or has expired. Or the client application associated with the access token does not exist any longer.
In this case, the ResponseContent property returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the resource server wants to return an error response to the client application in the way that complies with RFC 6750, the string returned from the ResponseContent property can be used as the value of the WWW-Authenticate header. The following is an example response which complies with RFC 6750.
When the value of the Action property is IntrospectionAction.FORBIDDEN, it means that the access token does not cover the required scopes or that the subject associated with the access token is different from the subject specified by the API call.
In this case, the ResponseContent property returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the protected resource of the resource server wants to return an error response to the client application in the way that complies with RFC 6750, the string returned from the ResponseContent property can be used as the value of the WWW-Authenticate header. The following is an example response which complies with RFC 6750.
When the value of the Action property is IntrospectionAction.OK, it means that the access token which the client application presented is valid (= exists and has not expired). The resource server is supposed to return the proteced resource to the client application.
In this case, the ResponseContent property returns "Bearer error=\"invalid_request"". This is the simplest string which can be used as the value of the WWW-Authenticate header to indicate "400 Bad
Request". The resource server may use this string to tell the client application that the request was bad. But in such a case, if possible, the resource server should generate a more informative error message to help developers of client applications. The following is an example error response which complies with RFC 6750.
Basically, the ResponseContent property returns a string which describes the error in the format of RFC 6750 (OAuth 2.0 Bearer Token Usage), so if the resource server has selected "Bearer" as the token type, the string returned from the ResponseContent property can be used directly as the value for the WWW-Authenticate header. However, if the service has selected another different token type, the resource server has to generate error message for itself.
Since version 2.1, Authlete provides a feature to issue access tokens in JWT format. This feature can be enabled by setting a non-null value to the AccessTokenSignAlg property of the service (see the description of the Service class for details). /api/auth/introspection API can accept access tokens in JWT format. However, note that the API does not return information contained in a given JWT-based access token but returns information stored in the database record which corresponds to the given JWT-based access token. Because attributes of the database record can be modified after the access token is issued (for example, by using /api/auth/token/update API), information returned by /api/auth/introspection API and information the given JWT-based access token holds may be different.
Property Documentation
◆ AccessTokenResources
|
getset |
The target resources of the access token.
The target resources held by this property may be the same as or different from the ones held by the Resources property.
In some flows, the initial request and the subsequent token request are sent to different endpoints. Example flows are the authorization code flow, the refresh token flow, the CIBA Ping mode, the CIBA Poll mode and the device flow. In these flows, not only the initial request but also the subsequent token request can include the resource request parameters. The purpose of the resource request parameters in the token request is to narrow the range of the target resources from the original set of target resources requested by the preceding initial request. If narrowing down is performed, the target resources held by the Resources property and the ones held by this AccessTokenResources property are different. This property holds the narrowed set of target resources.
Since version 1.4.0.
◆ Action
|
getset |
The next action that the resource server should take.
◆ CertificateThumbprint
|
getset |
The thumbprint of the client certificate which is associated with the access token.
If the access token is bound to a client certificate, this property holds the thumbprint of the client certificate.
Since version 1.0.9.
◆ ClientId
|
getset |
The client ID of the client application to which the access token has been issued.
◆ ClientIdAlias
|
getset |
The client ID alias when the authorization request or the token request for the access token was made. Note that this value may be different from the current client ID alias.
Since version 1.1.0.
◆ ExpiresAt
|
getset |
The time at which the access token will expire. The value is represented as milliseconds since the Unix epoch (1970-Jan-1).
◆ IsActive
|
getset |
The flag which indicates whether the access token is active (= exists and has not expired). This property is just an alias of the IsUsable property. The reason this property was added is to mitigate confusion that those who are familiar with RFC 7662 (OAuth 2.0 Token Introspection) may have.
Since version 1.0.6.
◆ IsClientIdAliasUsed
|
getset |
The flag which indicates whether the client ID alias was sed when the authorization request or the token request for the access token was made.
Since version 1.1.0.
◆ IsExistent
|
getset |
The flag which indicates whether the access token exists or not.
◆ IsRefreshable
|
getset |
The flag which indicates whether the access token can be refreshed using the associated refresh token. Even if there exists a refresh token associated with the access token, this property returns false if the refresh token has already expired.
◆ IsSufficient
|
getset |
The flag which indicates whether the access token covers the required scopes.
◆ IsUsable
|
getset |
The flag which indicates whether the access token is usable (= exists and has not expired).
◆ Properties
|
getset |
Arbitrary properties associated with the access token.
Since version 1.1.0.
◆ Resources
|
getset |
The target resources. This represents the resources specified by the resource request parameters or by the resource property in the request object. See RFC 8707 (Resource Indicators for OAuth 2.0) for details.
Since version 1.4.0.
◆ ResponseContent
|
getset |
The response content which can be used as a part of the response to the client application.
◆ Scopes
|
getset |
Scopes that are associated with the access token.
◆ Subject
|
getset |
The subject (= unique identifier) of the end-user (= resource owner) who allowed the authorization server to issue the access token to the client application.
The documentation for this class was generated from the following file:
- Authlete/Dto/IntrospectionResponse.cs
