001/*
002 * oauth2-oidc-sdk
003 *
004 * Copyright 2012-2016, Connect2id Ltd and contributors.
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use
007 * this file except in compliance with the License. You may obtain a copy of the
008 * License at
009 *
010 *    http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software distributed
013 * under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
014 * CONDITIONS OF ANY KIND, either express or implied. See the License for the
015 * specific language governing permissions and limitations under the License.
016 */
017
018package com.nimbusds.oauth2.sdk.auth;
019
020
021import com.nimbusds.oauth2.sdk.id.Identifier;
022import net.jcip.annotations.Immutable;
023
024
025/**
026 * Client authentication method at the Token endpoint.
027 *
028 * <p>Constants are provided for four client authentication methods:
029 *
030 * <ul>
031 *     <li>{@link #CLIENT_SECRET_BASIC client_secret_basic} (default)
032 *     <li>{@link #CLIENT_SECRET_POST client_secret_post}
033 *     <li>{@link #CLIENT_SECRET_JWT client_secret_jwt}
034 *     <li>{@link #PRIVATE_KEY_JWT private_key_jwt}
035 *     <li>{@link #TLS_CLIENT_AUTH tls_client_auth}
036 *     <li>{@link #SELF_SIGNED_TLS_CLIENT_AUTH self_signed_tls_client_auth}
037 *     <li>{@link #NONE none}
038 * </ul>
039 *
040 * <p>Use the constructor to define a custom client authentication method.
041 *
042 * <p>Related specifications:
043 *
044 * <ul>
045 *     <li>OAuth 2.0 (RFC 6749), section 2.3.
046 *     <li>OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591), section
047 *         2.
048 *     <li>OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound
049 *         Access Tokens (draft-ietf-oauth-mtls-07), section 2.
050 * </ul>
051 */
052@Immutable
053public final class ClientAuthenticationMethod extends Identifier {
054
055
056        /**
057         * Clients that have received a client secret from the authorisation 
058         * server authenticate with the authorisation server in accordance with
059         * section 3.2.1 of OAuth 2.0 using HTTP Basic authentication. This is 
060         * the default if no method has been registered for the client.
061         */
062        public static final ClientAuthenticationMethod CLIENT_SECRET_BASIC = 
063                new ClientAuthenticationMethod("client_secret_basic");
064
065
066        /**
067         * Clients that have received a client secret from the authorisation 
068         * server authenticate with the authorisation server in accordance with
069         * section 3.2.1 of OAuth 2.0 by including the client credentials in 
070         * the request body.
071         */
072        public static final ClientAuthenticationMethod CLIENT_SECRET_POST =
073                new ClientAuthenticationMethod("client_secret_post");
074
075
076        /**
077         * Clients that have received a client secret from the authorisation 
078         * server, create a JWT using an HMAC SHA algorithm, such as HMAC 
079         * SHA-256. The HMAC (Hash-based Message Authentication Code) is
080         * calculated using the value of client secret as the shared key. The 
081         * client authenticates in accordance with section 2.2 of (JWT) Bearer
082         * Token Profiles and OAuth 2.0 Assertion Profile. 
083         */
084        public static final ClientAuthenticationMethod CLIENT_SECRET_JWT =
085                new ClientAuthenticationMethod("client_secret_jwt");
086
087
088        /**
089         * Clients that have registered a public key sign a JWT using the RSA 
090         * algorithm if a RSA key was registered or the ECDSA algorithm if an 
091         * Elliptic Curve key was registered (see JWA for the algorithm 
092         * identifiers). The client authenticates in accordance with section 
093         * 2.2 of (JWT) Bearer Token Profiles and OAuth 2.0 Assertion Profile.
094         */
095        public static final ClientAuthenticationMethod PRIVATE_KEY_JWT =
096                new ClientAuthenticationMethod("private_key_jwt");
097        
098        
099        /**
100         * PKI mutual TLS OAuth client authentication. See OAuth 2.0 Mutual TLS
101         * Client Authentication and Certificate Bound Access Tokens, section
102         * 2.1.
103         */
104        public static final ClientAuthenticationMethod TLS_CLIENT_AUTH =
105                new ClientAuthenticationMethod("tls_client_auth");
106        
107        
108        /**
109         * Self-signed certificate mutual TLS OAuth client authentication. See
110         * OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound
111         * Access Tokens, section 2.2.
112         */
113        public static final ClientAuthenticationMethod SELF_SIGNED_TLS_CLIENT_AUTH =
114                new ClientAuthenticationMethod("self_signed_tls_client_auth");
115
116
117        /**
118         * The client is a public client as defined in OAuth 2.0 and does not
119         * have a client secret.
120         */
121        public static final ClientAuthenticationMethod NONE =
122                new ClientAuthenticationMethod("none");
123
124
125        /**
126         * Gets the default client authentication method.
127         *
128         * @return {@link #CLIENT_SECRET_BASIC}
129         */
130        public static ClientAuthenticationMethod getDefault() {
131
132                return CLIENT_SECRET_BASIC;
133        }
134
135
136        /**
137         * Creates a new client authentication method with the specified value.
138         *
139         * @param value The authentication method value. Must not be 
140         *              {@code null} or empty string.
141         */
142        public ClientAuthenticationMethod(final String value) {
143
144                super(value);
145        }
146
147
148        /**
149         * Parses a client authentication method from the specified value.
150         *
151         * @param value The authentication method value. Must not be
152         *              {@code null} or empty string.
153         *
154         * @return The client authentication method.
155         */
156        public static ClientAuthenticationMethod parse(final String value) {
157
158                if (value.equals(CLIENT_SECRET_BASIC.getValue())) {
159                        return CLIENT_SECRET_BASIC;
160                } else if (value.equals(CLIENT_SECRET_POST.getValue())) {
161                        return CLIENT_SECRET_POST;
162                } else if (value.equals(CLIENT_SECRET_JWT.getValue())) {
163                        return CLIENT_SECRET_JWT;
164                } else if (value.equals(PRIVATE_KEY_JWT.getValue())) {
165                        return PRIVATE_KEY_JWT;
166                } else if (value.equalsIgnoreCase(TLS_CLIENT_AUTH.getValue())) {
167                        return TLS_CLIENT_AUTH;
168                } else if (value.equalsIgnoreCase(SELF_SIGNED_TLS_CLIENT_AUTH.getValue())) {
169                        return SELF_SIGNED_TLS_CLIENT_AUTH;
170                } else if (value.equals(NONE.getValue())) {
171                        return NONE;
172                } else {
173                        return new ClientAuthenticationMethod(value);
174                }
175        }
176
177
178        @Override
179        public boolean equals(final Object object) {
180        
181                return object instanceof ClientAuthenticationMethod &&
182                       this.toString().equals(object.toString());
183        }
184}