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;
019
020
021import net.jcip.annotations.Immutable;
022
023import com.nimbusds.oauth2.sdk.id.Identifier;
024
025
026/**
027 * Authorisation response mode.
028 *
029 * <p>Related specifications:
030 *
031 * <ul>
032 *     <li>OAuth 2.0 Multiple Response Type Encoding Practices 1.0
033 *     <li>OAuth 2.0 Form Post Response Mode 1.0
034 *     <li>Financial-grade API: JWT Secured Authorization Response Mode for
035 *         OAuth 2.0 (JARM)
036 * </ul>
037 */
038@Immutable
039public final class ResponseMode extends Identifier {
040
041
042        /**
043         * The authorisation response parameters are encoded in the query
044         * string added to the {@code redirect_uri} when redirecting back to
045         * the client.
046         */
047        public static final ResponseMode QUERY = new ResponseMode("query");
048
049
050        /**
051         * The authorisation response parameters are encoded in the fragment
052         * added to the {@code redirect_uri} when redirecting back to the
053         * client.
054         */
055        public static final ResponseMode FRAGMENT = new ResponseMode("fragment");
056
057
058        /**
059         * The authorisation response parameters are encoded as HTML form
060         * values that are auto-submitted in the User Agent, and thus are
061         * transmitted via the HTTP POST method to the client, with the result
062         * parameters being encoded in the body using the
063         * {@code application/x-www-form-urlencoded} format. The action
064         * attribute of the form MUST be the client's redirection URI. The
065         * method of the form attribute MUST be POST.
066         */
067        public static final ResponseMode FORM_POST = new ResponseMode("form_post");
068        
069        
070        /**
071         * The authorisation response parameters are packaged in a JSON Web
072         * Token (JWT) which is returned as a {@code response} query parameter
073         * added to the {@code redirect_uri} when redirecting back to the
074         * client.
075         */
076        public static final ResponseMode QUERY_JWT = new ResponseMode("query.jwt");
077        
078        
079        /**
080         * The authorisation response parameters are packaged in a JSON Web
081         * Token (JWT) which is returned as a {@code response} fragment
082         * parameter added to the {@code redirect_uri} when redirecting back to
083         * the client.
084         */
085        public static final ResponseMode FRAGMENT_JWT = new ResponseMode("fragment.jwt");
086        
087        
088        /**
089         * The authorisation response parameters are packaged in a JSON Web
090         * Token (JWT) which is transmitted via the HTTP POST method to the
091         * client. The action attribute of the form MUST be the client's
092         * redirection URI. The method of the form attribute MUST be POST.
093         */
094        public static final ResponseMode FORM_POST_JWT = new ResponseMode("form_post.jwt");
095        
096        
097        /**
098         * The authorisation response parameters are packaged in a JSON Web
099         * Token (JWT) which is returned as a {@code response} parameter using
100         * the redirect encoding ({@link #QUERY_JWT query.jwt},
101         * {@link #FRAGMENT_JWT fragment.jwt} for the requested
102         * {@code response_type}.
103         *
104         * <p>See {@link #resolve(ResponseMode, ResponseType)}.
105         */
106        public static final ResponseMode JWT = new ResponseMode("jwt");
107        
108        
109        private static final long serialVersionUID = -5607166526553472087L;
110        
111        
112        /**
113         * Resolves the requested response mode.
114         *
115         * <p>If the {@link #JWT jwt} response mode shortcut from JARM is
116         * explicitly requested expands it to {@link #QUERY_JWT query.jwt} or
117         * {@link #FRAGMENT_JWT fragment.jwt} depending on the response type
118         * ({@code response_type}).
119         *
120         * @param rm The explicitly requested response mode
121         *           ({@code response_mode}), {@code null} if not specified.
122         * @param rt The response type ({@code response_type}), {@code null} if
123         *           not known.
124         *
125         * @return The resolved response mode.
126         */
127        public static ResponseMode resolve(final ResponseMode rm, final ResponseType rt) {
128                
129                if (rm != null) {
130                        // Explicitly requested response_mode
131                        if (ResponseMode.JWT.equals(rm)) {
132                                // https://openid.net//specs/openid-financial-api-jarm.html#response-mode-jwt
133                                if (rt != null && (rt.impliesImplicitFlow() || rt.impliesHybridFlow())) {
134                                        return ResponseMode.FRAGMENT_JWT;
135                                } else {
136                                        return ResponseMode.QUERY_JWT;
137                                }
138                        }
139                        
140                        return rm;
141                        
142                } else if (rt != null && (rt.impliesImplicitFlow() || rt.impliesHybridFlow())) {
143                        return ResponseMode.FRAGMENT;
144                } else {
145                        // assume query in all other cases
146                        return ResponseMode.QUERY;
147                }
148        }
149        
150        
151        /**
152         * Resolves the appropriate JWT-secured authorisation response mode
153         * (JARM) for the specified response type
154         *
155         * @param rt The response type ({@code response_type}). Must not be
156         *           {@code null}.
157         *
158         * @return A {@link #QUERY_JWT query.jwt} or {@link #FRAGMENT_JWT
159         *         fragment.jwt} response mode.
160         */
161        public static ResponseMode resolveJARM(final ResponseType rt) {
162                
163                if (rt.impliesImplicitFlow() || rt.impliesHybridFlow()) {
164                        return ResponseMode.FRAGMENT_JWT;
165                } else {
166                        return ResponseMode.QUERY_JWT;
167                }
168        }
169
170
171        /**
172         * Creates a new authorisation response mode with the specified value.
173         *
174         * @param value The response mode value. Must not be {@code null}.
175         */
176        public ResponseMode(final String value) {
177
178                super(value);
179        }
180
181
182        @Override
183        public boolean equals(final Object object) {
184
185                return object instanceof ResponseMode &&
186                        this.toString().equals(object.toString());
187        }
188}