Location: This method is in the class %SYS.OAuth2.ValidationOpens in a new tab.
ClassMethod ValidateJWT(applicationName As %String,
accessToken As %String,
scope As %String,
aud As %String,
Output jsonObject As %RegisteredObject,
Output securityParameters As %String,
Output sc As %Status) As %Boolean
Use this method only if the access token is a JWT (rather than an opaque token).
This method decrypts the JWT if necessary, validates the JWT, and creates an object (jsonObject) to contain the JWT properties. To validate the JWT, the method checks the audience (if aud is specified), issuer endpoint (must match that specified in server description), and scope (if scope is specified). The method also makes sure the access token has not expired. Both signed and unsigned JWTs are accepted. If the JWT is signed, the method checks the signature.
This method returns 1 if the JWT is valid or returns 0 otherwise. It also returns several arguments as output.
The arguments are as follows:
-
applicationName is the name of the client application.
-
accessToken is the JWT to be validated.
-
scope is a space-delimited list of scopes, for example: "scope1 scope2 scope3"
If scope is specified, the JWT must contain a scope claim that includes this scope.
-
aud specifies the audience that is using the token. If the token has an associated aud property (usually because the audience was specified when requesting the token), then aud is matched to the token audience. If aud is not specified, then no audience checking takes place.
-
jsonObject, which is returned as output, is a dynamic object that contains the claims in the JWT. This dynamic object contains properties such as aud, exp, iss, and so on. For details on dynamic objects, see Using JSON.
-
securityParameters, which is returned as output, is a multidimensional array that contains security information taken from the header, for optional additional use in verifying signatures, decrypting, or both.
This array contains the following nodes:
| Node |
Value |
| securityParameters("sigalg") |
The signature or MAC algorithm. Set only if the JWT is signed |
| securityParameters("keyalg") |
The key management algorithm |
| securityParameters("encalg") |
The content encryption algorithm |
The keyalg and encalg nodes are either both specified or both null.
-
sc, which is returned as output, contains the status code set by this method.
If this method returns success (1), examine jsonObject, and use the contained claims as needed to determine whether to allow access to the requested resource. Use securityParameters if needed.
Because the Oauth specification allows an application to accept both signed and unsigned JWTs, the ValidateJWT method does not reject an unsigned JWT. However, in many cases it is strongly recommended that your application implement stricter security by rejecting an unsigned JWT. You can determine whether the token passed into ValidateJWT was unsigned by inspecting the securityParameters array that is returned by the method. If securityParameters("sigalg") was not set, the token was unsigned. For example, the following code determines whether the token was unsigned and rejects it if it was:
Set tInitialValidationPassed = ##class(%SYS.OAuth2.Validation).ValidateJWT(tClientName, tAccessToken, "", "", .tJsonObj,.tSecurityParams, .tValidateStatus)
// the “sigalg” subscript is set only if the JWT was signed
Set tIsTokenSigned = $Data(tSecurityParams("sigalg"))#2
If 'tIsTokenSigned {
$$$ThrowStatus($System.Status.Error($$$AccessDenied))
}
