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        public static final ResponseMode JWT = new ResponseMode("jwt");
105        
106        
107        /**
108         * Resolves the requested response mode.
109         *
110         * @param rm The explicitly requested response mode
111         *           ({@code response_mode}), {@code null} if not specified.
112         * @param rt The response type ({@code response_type}), {@code null} if
113         *           not known.
114         *
115         * @return The resolved response mode.
116         */
117        public static ResponseMode resolve(final ResponseMode rm, final ResponseType rt) {
118                
119                if (rm != null) {
120                        // Explicitly requested response_mode
121                        if (ResponseMode.JWT.equals(rm)) {
122                                // https://openid.net//specs/openid-financial-api-jarm.html#response-mode-jwt
123                                if (rt != null && (rt.impliesImplicitFlow() || rt.impliesHybridFlow())) {
124                                        return ResponseMode.FRAGMENT_JWT;
125                                } else {
126                                        return ResponseMode.QUERY_JWT;
127                                }
128                        }
129                        
130                        return rm;
131                        
132                } else if (rt != null && (rt.impliesImplicitFlow() || rt.impliesHybridFlow())) {
133                        return ResponseMode.FRAGMENT;
134                } else {
135                        // assume query in all other cases
136                        return ResponseMode.QUERY;
137                }
138        }
139
140
141        /**
142         * Creates a new authorisation response mode with the specified value.
143         *
144         * @param value The response mode value. Must not be {@code null}.
145         */
146        public ResponseMode(final String value) {
147
148                super(value);
149        }
150
151
152        @Override
153        public boolean equals(final Object object) {
154
155                return object instanceof ResponseMode &&
156                        this.toString().equals(object.toString());
157        }
158}