1 package com.atlassian.asap.service.api;
2
3 import com.atlassian.asap.api.exception.CannotRetrieveKeyException;
4 import com.atlassian.asap.api.exception.InvalidTokenException;
5
6 import javax.json.JsonObject;
7 import java.time.Duration;
8 import java.util.Arrays;
9 import java.util.Optional;
10
11 /**
12 * A builder-style tool for generating an HTTP {@code Authorization} header value that contains an ASAP token.
13 *
14 * @since 2.8
15 */
16 public interface AuthorizationBuilder {
17 /**
18 * Specifies the subject of the token.
19 *
20 * @param subject the subject to specify, or {@code empty()} to omit this field from the token
21 * @return {@code this}
22 */
23 AuthorizationBuilder subject(Optional<String> subject);
24
25 /**
26 * Specifies the intended audience(s) for the token.
27 *
28 * @param audience the audience(s) to specify in the token
29 * @return {@code this}
30 */
31 default AuthorizationBuilder audience(String... audience) {
32 return audience(Arrays.asList(audience));
33 }
34
35 /**
36 * Specifies the intended audience(s) for the token.
37 *
38 * @param audience the audience(s) to specify in the token
39 * @return {@code this}
40 */
41 AuthorizationBuilder audience(Iterable<String> audience);
42
43 /**
44 * Specifies how long the token will remain valid.
45 *
46 * @param duration how long the token should remain valid ({@code empty()} to use the default)
47 * @return {@code this}
48 */
49 AuthorizationBuilder expiration(Optional<Duration> duration);
50
51 /**
52 * Permits the inclusion of additional parameters that are not covered by any of the standard JWT claims.
53 * <p>
54 * Other than the requirement that it must be expressible in JSON, no other explicit restrictions are given for the
55 * contents of this field. Practical restrictions, such as any maximum size for this information or what the
56 * consequences might be for exceeding it, are left unspecified.
57 * </p>
58 *
59 * @param claims the additional information, if any, to include as extended information in the token
60 * @return {@code this}
61 */
62 AuthorizationBuilder customClaims(Optional<JsonObject> claims);
63
64 /**
65 * Generates a signed token and forms a value that is appropriate to use as an "Authorization" HTTP header.
66 *
67 * @return the value that should be specified as an {@code Authorization} header in HTTP requests
68 * @throws CannotRetrieveKeyException the private key cannot be loaded
69 * @throws InvalidTokenException the parameters supplied for the token were invalid
70 */
71 String build() throws InvalidTokenException, CannotRetrieveKeyException;
72 }