Note: Deprecated in Version 1.05.
JSON Web Token (JWT) UserIdentityTokens can be passed to the Server using the IssuedIdentityToken. The body of the token is a string that contains the JWT as defined in RFC 7519.
Servers that support JWT authentication shall provide a UserTokenPolicy which specifies the Authorization Service which provides the token and the parameters needed to access that service. The parameters are specified by a JSON object specified as the issuerEndpointUrl. The contents of this JSON object are described in Table 54. The general UserTokenPolicy settings for JWT are defined in Table 53.
Table 53 – JWT UserTokenPolicy
|
Name |
Description |
|
tokenType |
ISSUEDTOKEN_3 |
|
issuedTokenType |
|
|
issuerEndpointUrl |
For JWTs this is a JSON object with fields defined in Table 54. |
Table 54 – JWT IssuerEndpointUrl Definition
|
Name |
Type |
Required |
Description |
|
IssuerEndpointUrl |
JSON object |
Yes |
Specifies the parameters for a JWT UserIdentityToken. |
|
ua:resourceId |
String |
Yes |
The URI identifying the Server to the Authorization Service. The default value is the Server’s ApplicationUri. |
|
ua:authorityUrl |
String |
Yes |
The base URL for the Authorization Service. This URL may be used to discover additional information about the authority. This field is equivalent to the "issuer" defined in OpenID-Discovery. |
|
ua:authorityProfileUri |
String |
Yes |
The profile that defines the interactions with the authority. The default URI is "http://opcfoundation.org/UA/Authorization#OPCUA". A set of possible authorities are in the Profile: http://opcfoundation.org/UA-Profile/Security/UserToken/Server/JsonWebToken |
|
ua:tokenEndpoint |
String |
Depends on authorityProfileUri |
A path relative to the base URL used to request Access Tokens. If the authorityProfileUri is OPCUA, then this is the NodeId of the AuthorizationService Object encoded as described in 5.4.2.10. This field is equivalent to the "token_endpoint" defined in OpenID-Discovery. |
|
ua:authorizationEndpoint |
String |
No |
A path relative to the base URL used to validate user credentials. If the authorityProfileUri is OPCUA, then this is the NodeId of the UserTokenProfile Property of the AuthorizationService Object encoded as described in 5.4.2.10. This field is equivalent to the "authorization_endpoint" defined in OpenID-Discovery. |
|
ua:requestTypes |
JSON array String |
No |
The list of request types supported by the authority. The possible values are described in 6.5.3.2 to 6.5.3.4. If not specified the default is "authorization_code". |
|
ua:scopes |
JSON array String |
No |
A list of Scopes that are understood by the Server. If not specified, the Client may be able to access any Scope supported by the Authorization Service. This field is equivalent to the "scopes_supported" defined in OpenID-Discovery. |
The JWT supports signatures using asymmetric cryptography which implies that Servers which accept the Access Token must have access to the Certificate used by the Authorization Service.
All Access Tokens shall have a signature created by the token issuer.
Access Tokens expire and all Servers should revoke any privileges granted to the Session when the Access Token expires. If the Server allows for anonymous users, the Server may allow the Session to stay open but treat it as an anonymous user. If the Server does not allow anonymous users, it should close the Session immediately.
Clients know when the Access Token will expire and should request a new Access Token and call ActivateSession before the old Access Token expires.
The JWT format allows the Authorization Service to insert any number of fields. The mandatory fields are defined in RFC 7519. Some additional fields are defined in Table 55.
Table 55 – JWT Access Token Claims
|
Name |
JSON Type |
Required |
Description |
|
sub |
string |
Yes |
The subject for the token. This is the equivalent of a UserName or an X509 subjectName. If the field "iss" is not present, it shall be a globally unique identifier. If "iss" is present, it shall be unique within the context of the “iss”. |
|
iss |
string |
No |
The URI of the issuer. For the authorityProfileUri "http://opcfoundation.org/UA/Authorization#OPCUA" it shall be the ServiceUri of the Authorization Service (see OPC 10000-12). |
|
aud |
string |
Yes |
Shall be the resourceId specified in the UserTokenPolicy (see 6.5.2.2). This is usually the Server ApplicationUri. |
|
exp |
number |
Yes |
The expiration time of the token. It shall be checked before accepting the token. |
|
groups |
array |
No |
A list of groups which are assigned to the subject. Usually, a list of unique identifiers for specific security groups. For example, Azure AD user account groups may be returned in this claim. |
|
roles |
array |
No |
A list of roles which are assigned to the subject. Roles apply to the requestor and describe what the requestor can do with the resource. Roles are list of unique names for roles known to the Authorization Service. These values are typically mapped to the Roles defined in OPC 10000-3 using the identity mappings defined in OPC 10000-18. |
|
nbf |
number |
No |
The time when the token becomes valid. If present, it shall be checked before accepting the token. |
|
cnf |
object |
No |
The thumbprint of the Certificate which shall be used with the token. If present, the Server shall not accept a token unless the SecureChannel has been created with the Certificate identified by this field. The field is a JSON object with a single "x5t#S256" field which specifies the thumbprint of the Certificate. See RFC 8705. |
The OAuth2 Authorization Framework (see RFC 6749) provides a web-based mechanism to request claims-based Access Tokens from an Authorization Service (AS) that is supported by many major companies providing cloud infrastructure. These Access Tokens are passed to a Server by a Client in a UserIdentityToken as described in OPC 10000-4.
The OpenID Connect specification (see OpenID) builds on the OAuth2 specification by defining the contents of the Access Tokens more strictly.
The OAuth2 specification supports a number of use cases (called ‘flows’) to handle different application requirements. The use cases that are relevant to OPC UA are discussed below.
The authorization code flow is available to Clients which allow interaction with a human user. The Client application displays a window with a web browser which sends an HTTP GET to the Identity Provider. When the human user enters credentials that the Identity Provider validates the Identity Provider returns an authorization code which is passed to the Authorization Service. The Authorization Service validates the code and returns an Access Token to the Client.
The complete flow is described in RFC 6749, 4.1.
A requestType of "authorization_code" in the UserTokenPolicy (see 6.5.2) means the Authorization Service supports the authorization code flow.
The refresh token flow applies when a Client application has access to a refresh token returned in a previous response to an authorization code request. The refresh token allows applications to skip the step that requires human interaction with the Identity Provider. This flow is initiated when the Client sends the refresh token to Authorization Service which validates it and returns an Access Token. A Client that saves the refresh token for later use shall use encryption or other means to ensure the refresh token cannot be accessed by unauthorized parties.
The complete flow is described in RFC 6749, 6.
A requestType is not defined since support for refresh token is determined by checking the response to an authorization code request.
The client credentials flow applies when a Client application cannot prompt a human user for input. This flow requires a secret know to the Authorization Service which the Client application can protect. This flow is initiated when the Client sends the client_secret to Authorization Service which validates it and returns an Access Token.
The complete flow is described in RFC 6749, 4.4.
A requestType of "client_credentials" in the UserTokenPolicy (see 6.5.2) means the Authorization Service supports the client credentials flow.