com.atlassian.asap.service.api

Interface TokenValidator

All Known Implementing Classes:

AbstractTokenValidator, TokenValidatorImpl

public interface TokenValidator

A builder-style tool for specifying and enforcing ASAP authentication and authorization requirements.

Since:

2.8

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	TokenValidator.Policy Specifies the desired enforcement policy for ASAP authentication.

Method Summary

Modifier and Type	Method and Description
TokenValidator	audience(Iterable<String> additionalAudienceValues) As for audience(String...).
default TokenValidator	audience(String... additionalAudienceValues) Specifies the audience(s) that will be accepted.
TokenValidator	impersonationIssuer(Iterable<String> impersonationIssuers) As for impersonationIssuer(String...).
default TokenValidator	impersonationIssuer(String... impersonationIssuers) Specifies the issuer(s) that are authorized to impersonate a user while using this resource.
TokenValidator	issuer(Iterable<String> authorizedIssuers) As for issuer(String...).
default TokenValidator	issuer(String... authorizedIssuers) Specifies the issuer(s) that are authorized to use this resource.
TokenValidator	policy(TokenValidator.Policy policy) Specifies the validation policy for this validator.
TokenValidator	subject(Iterable<String> authorizedSubjects) As for subject(String...).
default TokenValidator	subject(String... authorizedSubjects) Specifies the effective subject(s) that are authorized to use this resource.
TokenValidator	subjectImpersonation(boolean subjectImpersonation) Deprecated. move/copy issuers that are allowed to impersonate users from the 'issuer' to the 'impersonationIssuer' list
ValidationResult	validate(Optional<String> authHeader) Perform the validation.

Method Detail

issuer

default TokenValidator issuer(String... authorizedIssuers)

Specifies the issuer(s) that are authorized to use this resource. Issuers in this list would be able to execute this resource without authorization checks. Note, it's possible to list the same issuer both in 'issuer' and in 'subjectImpersonationIssuer'.

Issuer validation is appropriate unless the resource is intended to be used as an open service that many different issuers can access.

Failures reported as: ValidationResult.Decision.NOT_AUTHORIZED

Parameters:

authorizedIssuers - the issuers that are authorized to use this resource; null elements are not permitted

Returns:

this

issuer

TokenValidator issuer(Iterable<String> authorizedIssuers)

As for issuer(String...).

Parameters:

authorizedIssuers - as for issuer(String...)

Returns:

this

impersonationIssuer

default TokenValidator impersonationIssuer(String... impersonationIssuers)

Specifies the issuer(s) that are authorized to impersonate a user while using this resource. Issuers in this list would be able to execute this resource authorized as a certain user. Typically username comes as a subject in ASAP hence the name prefix.

Issuer validation is required to be used if the resource is intended to be used in the context of a user, with all the access checks

Failures reported as: ValidationResult.Decision.NOT_AUTHORIZED

Parameters:

impersonationIssuers - the issuers that are authorized to impersonate a user while using this resource; null elements are not permitted

Returns:

this

impersonationIssuer

TokenValidator impersonationIssuer(Iterable<String> impersonationIssuers)

As for impersonationIssuer(String...).

Parameters:

impersonationIssuers - as for impersonationIssuer(String...)

Returns:

this

subjectImpersonation

@Deprecated
TokenValidator subjectImpersonation(boolean subjectImpersonation)

Deprecated. move/copy issuers that are allowed to impersonate users from the 'issuer' to the 'impersonationIssuer' list

Specifies that the subject is to be interpreted as identifying a specific user whose identity should be assumed for this request.

The subject is ignored by default. If subject impersonation is enabled, then the subject is understood to identify a user known to the application, or anonymous access when the subject is not specified. If subject impersonation is enabled, then the issuer whitelist MUST be provided, or all tokens will be rejected.

The validation service only approves the request for subject impersonation. The actual implementation is left up to the surrounding framework.

Parameters:

subjectImpersonation - true to use subject impersonation

Returns:

this

subject

default TokenValidator subject(String... authorizedSubjects)

Specifies the effective subject(s) that are authorized to use this resource.

The subject is ignored by default. If an explicit whitelist is provided, then the effective subject must be in it for the token to pass authorization. The effective subject is defined as:

• The token's subject, if it is specified.
• The token's issuer, if the subject is not specified and subject impersonation is not used.
• Nobody at all, if the subject is not specified and subject impersonation is enabled.

Failures reported as: ValidationResult.Decision.NOT_AUTHORIZED

Parameters:

authorizedSubjects - the subjects that are authorized to use this resource; null elements are not permitted, and an empty list disables this check.

Returns:

this

subject

TokenValidator subject(Iterable<String> authorizedSubjects)

As for subject(String...).

Parameters:

authorizedSubjects - as for subject(String...)

Returns:

this

audience

default TokenValidator audience(String... additionalAudienceValues)

Specifies the audience(s) that will be accepted.

By default, the globally configured audience is assumed to be the expected value, and it is always accepted. If the token does not specify either the globally configured audience or one of the alternate values (if any) provided here, then it will not pass authentication.

For security reasons, it is not possible to disable audience validation. Note: This is an authentication failure, because the token itself is not accepted as valid if it is meant for some other service.

Failures reported as: ValidationResult.Decision.NOT_AUTHENTICATED

Parameters:

additionalAudienceValues - the audience values that, in addition to the globally configured default, are acceptable for other services to specify when creating a token to access this resource

Returns:

this

audience

TokenValidator audience(Iterable<String> additionalAudienceValues)

As for audience(String...).

Parameters:

additionalAudienceValues - as for audience(String...)

Returns:

this

policy

TokenValidator policy(TokenValidator.Policy policy)

Specifies the validation policy for this validator.

By default, the validator will use TokenValidator.Policy.REQUIRE. If those are not the desired authentication semantics, then this method can be used to specify one of the other policies, instead. The most useful ones are probably TokenValidator.Policy.IGNORE (to disable ASAP authentication when it might otherwise have been inherited from a superclass or the surrounding context) and TokenValidator.Policy.OPTIONAL, to allow ASAP authentication to be validated when it is attempted, but without mandating its use.

Parameters:

policy - the enforcement policy to use

Returns:

this

validate

ValidationResult validate(Optional<String> authHeader)

Perform the validation.

Parameters:

authHeader - the contents of the Authorization header from the HTTP request, if any.

Returns:

the outcome from validating the authHeader