1 package com.atlassian.sal.api.permission;
2
3 import com.atlassian.annotations.PublicApi;
4
5 /**
6 * Allows clients to easily verify that the caller has sufficient permission to access the resource.
7 * {@code PermissionEnforcer} takes all permissions into account from the current security context. This includes the
8 * calling user's permissions, but also any permission escalations or restrictions that may be in effect (e.g.
9 * read-only personal access tokens).
10 * <p>
11 * The host application ensures that any thrown {@link AuthorisationException} is handled correctly:
12 *
13 * <h3>Web requests</h3>
14 * <ul>
15 * <li>If the user is not authenticated, the user will be redirected to the login page</li>
16 * <li>If the user is authenticated, but lacks the required authorisation, an appropriate error page will be
17 * displayed</li>
18 * </ul>
19 *
20 * <h3>REST requests</h3>
21 * <ul>
22 * <li>If the user is not authenticated, a 401 error response is returned</li>
23 * <li>If the user is authenticated, but lacks the required authorisation, a 403 error is returned</li>
24 * </ul>
25 *
26 * @since 3.2
27 */
28 @PublicApi
29 public interface PermissionEnforcer {
30
31 /**
32 * Verifies that the current security context has sufficient authorisation to perform administration tasks. This can
33 * either be because the user is an administrator, or because the security context is running with temporarily
34 * elevated permissions.
35 *
36 * @throws AuthorisationException if the current security context lacks the required authorisation
37 * @throws NotAuthenticatedException if the current security context lacks the required authorisation <em>and</em>
38 * the current user is not authenticated
39 */
40 void enforceAdmin() throws AuthorisationException;
41
42 /**
43 * Verifies that the current user is authenticated.
44 *
45 * @throws NotAuthenticatedException if the user is not authenticated
46 */
47 void enforceAuthenticated() throws NotAuthenticatedException;
48
49 /**
50 * Verifies that the current security context has sufficient authorisation to perform system administration tasks.
51 * This can either be because the user is a system administrator, or because the security context is running with
52 * temporarily elevated permissions.
53 *
54 * @throws AuthorisationException if the current security context lacks the required authorisation
55 * @throws NotAuthenticatedException if the current security context lacks the required authorisation <em>and</em>
56 * the current user is not authenticated
57 */
58 void enforceSystemAdmin() throws AuthorisationException;
59
60 /**
61 * Tests whether the current security context has sufficient authorisation to perform administration tasks. This can
62 * either be because the user is an administrator, or because the security context is running with temporarily
63 * elevated permissions.
64 *
65 * @return {@code true} if the current security context has sufficient authorisation to perform administration
66 * tasks, otherwise {@code false}
67 */
68 boolean isAdmin();
69
70 /**
71 * @return {@code true} if the current user is authenticated
72 */
73 boolean isAuthenticated();
74
75 /**
76 * Tests whether the current security context has sufficient authorisation to perform system administration tasks.
77 * This can either be because the user is a system administrator, or because the security context is running with
78 * temporarily elevated permissions.
79 *
80 * @return {@code true} if the current security context has sufficient authorisation to perform system
81 * administration tasks, otherwise {@code false}
82 */
83 boolean isSystemAdmin();
84 }