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 net.jcip.annotations.Immutable;
022
023import com.nimbusds.oauth2.sdk.id.Identifier;
024
025
026/**
027 * Client authentication method at the Token endpoint.
028 *
029 * <p>Constants are provided for four client authentication methods:
030 *
031 * <ul>
032 *     <li>{@link #CLIENT_SECRET_BASIC client_secret_basic} (default)
033 *     <li>{@link #CLIENT_SECRET_POST client_secret_post}
034 *     <li>{@link #CLIENT_SECRET_JWT client_secret_jwt}
035 *     <li>{@link #PRIVATE_KEY_JWT private_key_jwt}
036 *     <li>{@link #TLS_CLIENT_AUTH tls_client_auth}
037 *     <li>{@link #SELF_SIGNED_TLS_CLIENT_AUTH self_signed_tls_client_auth}
038 *     <li>{@link #REQUEST_OBJECT request_object}
039 *     <li>{@link #NONE none}
040 * </ul>
041 *
042 * <p>Use the constructor to define a custom client authentication method.
043 *
044 * <p>Related specifications:
045 *
046 * <ul>
047 *     <li>OAuth 2.0 (RFC 6749), section 2.3.
048 *     <li>OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591), section
049 *         2.
050 *     <li>OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound
051 *         Access Tokens (RFC 8705), section 2.
052 *     <li>OpenID Connect Federation 1.0.
053 * </ul>
054 */
055@Immutable
056public final class ClientAuthenticationMethod extends Identifier {
057        
058        
059        private static final long serialVersionUID = 1L;
060
061
062        /**
063         * Clients that have received a client secret from the authorisation 
064         * server authenticate with the authorisation server in accordance with
065         * section 3.2.1 of OAuth 2.0 using HTTP Basic authentication. This is 
066         * the default if no method has been registered for the client.
067         */
068        public static final ClientAuthenticationMethod CLIENT_SECRET_BASIC = 
069                new ClientAuthenticationMethod("client_secret_basic");
070
071
072        /**
073         * Clients that have received a client secret from the authorisation 
074         * server authenticate with the authorisation server in accordance with
075         * section 3.2.1 of OAuth 2.0 by including the client credentials in 
076         * the request body.
077         */
078        public static final ClientAuthenticationMethod CLIENT_SECRET_POST =
079                new ClientAuthenticationMethod("client_secret_post");
080
081
082        /**
083         * Clients that have received a client secret from the authorisation 
084         * server, create a JWT using an HMAC SHA algorithm, such as HMAC 
085         * SHA-256. The HMAC (Hash-based Message Authentication Code) is
086         * calculated using the value of client secret as the shared key. The 
087         * client authenticates in accordance with section 2.2 of (JWT) Bearer
088         * Token Profiles and OAuth 2.0 Assertion Profile. 
089         */
090        public static final ClientAuthenticationMethod CLIENT_SECRET_JWT =
091                new ClientAuthenticationMethod("client_secret_jwt");
092
093
094        /**
095         * Clients that have registered a public key sign a JWT using the RSA 
096         * algorithm if a RSA key was registered or the ECDSA algorithm if an 
097         * Elliptic Curve key was registered (see JWA for the algorithm 
098         * identifiers). The client authenticates in accordance with section 
099         * 2.2 of (JWT) Bearer Token Profiles and OAuth 2.0 Assertion Profile.
100         */
101        public static final ClientAuthenticationMethod PRIVATE_KEY_JWT =
102                new ClientAuthenticationMethod("private_key_jwt");
103        
104        
105        /**
106         * PKI mutual TLS OAuth client authentication. See OAuth 2.0 Mutual TLS
107         * Client Authentication and Certificate Bound Access Tokens (RFC
108         * 8705), section 2.1.
109         */
110        public static final ClientAuthenticationMethod TLS_CLIENT_AUTH =
111                new ClientAuthenticationMethod("tls_client_auth");
112        
113        
114        /**
115         * Self-signed certificate mutual TLS OAuth client authentication. See
116         * OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound
117         * Access Tokens (RFC 8705), section 2.2.
118         */
119        public static final ClientAuthenticationMethod SELF_SIGNED_TLS_CLIENT_AUTH =
120                new ClientAuthenticationMethod("self_signed_tls_client_auth");
121        
122        
123        /**
124         * Client authentication by means of a request object at the
125         * authorisation or PAR endpoints. Intended for OpenID Connect
126         * Federation 1.0 clients undertaking automatic registration. See
127         * OpenID Connect Federation 1.0.
128         */
129        public static final ClientAuthenticationMethod REQUEST_OBJECT =
130                new ClientAuthenticationMethod("request_object");
131
132
133        /**
134         * The client is a public client as defined in OAuth 2.0 and does not
135         * have a client secret.
136         */
137        public static final ClientAuthenticationMethod NONE =
138                new ClientAuthenticationMethod("none");
139
140
141        /**
142         * Gets the default client authentication method.
143         *
144         * @return {@link #CLIENT_SECRET_BASIC}
145         */
146        public static ClientAuthenticationMethod getDefault() {
147
148                return CLIENT_SECRET_BASIC;
149        }
150
151
152        /**
153         * Creates a new client authentication method with the specified value.
154         *
155         * @param value The authentication method value. Must not be 
156         *              {@code null} or empty string.
157         */
158        public ClientAuthenticationMethod(final String value) {
159
160                super(value);
161        }
162
163
164        /**
165         * Parses a client authentication method from the specified value.
166         *
167         * @param value The authentication method value. Must not be
168         *              {@code null} or empty string.
169         *
170         * @return The client authentication method.
171         */
172        public static ClientAuthenticationMethod parse(final String value) {
173
174                if (value.equals(CLIENT_SECRET_BASIC.getValue())) {
175                        return CLIENT_SECRET_BASIC;
176                } else if (value.equals(CLIENT_SECRET_POST.getValue())) {
177                        return CLIENT_SECRET_POST;
178                } else if (value.equals(CLIENT_SECRET_JWT.getValue())) {
179                        return CLIENT_SECRET_JWT;
180                } else if (value.equals(PRIVATE_KEY_JWT.getValue())) {
181                        return PRIVATE_KEY_JWT;
182                } else if (value.equalsIgnoreCase(TLS_CLIENT_AUTH.getValue())) {
183                        return TLS_CLIENT_AUTH;
184                } else if (value.equalsIgnoreCase(SELF_SIGNED_TLS_CLIENT_AUTH.getValue())) {
185                        return SELF_SIGNED_TLS_CLIENT_AUTH;
186                } else if (value.equalsIgnoreCase(REQUEST_OBJECT.getValue())) {
187                        return REQUEST_OBJECT;
188                } else if (value.equals(NONE.getValue())) {
189                        return NONE;
190                } else {
191                        return new ClientAuthenticationMethod(value);
192                }
193        }
194
195
196        @Override
197        public boolean equals(final Object object) {
198        
199                return object instanceof ClientAuthenticationMethod &&
200                       this.toString().equals(object.toString());
201        }
202}