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.token;
019
020
021import java.util.List;
022import java.util.Map;
023
024import net.jcip.annotations.Immutable;
025import net.minidev.json.JSONObject;
026
027import com.nimbusds.oauth2.sdk.ParseException;
028import com.nimbusds.oauth2.sdk.Scope;
029import com.nimbusds.oauth2.sdk.http.HTTPRequest;
030
031
032/**
033 * Bearer access token.
034 *
035 * <p>Example bearer access token serialised to JSON:
036 *
037 * <pre>
038 * {
039 *   "access_token" : "2YotnFZFEjr1zCsicMWpAA",
040 *   "token_type"   : "bearer",
041 *   "expires_in"   : 3600,
042 *   "scope"        : "read write"
043 * }
044 * </pre>
045 *
046 * <p>The above example token serialised to a HTTP Authorization header:
047 *
048 * <pre>
049 * Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
050 * </pre>
051 *
052 * <p>Related specifications:
053 *
054 * <ul>
055 *     <li>OAuth 2.0 (RFC 6749), sections 1.4 and 5.1.
056 *     <li>OAuth 2.0 Bearer Token Usage (RFC 6750).
057 * </ul>
058 */
059@Immutable
060public class BearerAccessToken extends AccessToken {
061        
062        
063        private static final long serialVersionUID = 2387121016151061194L;
064        
065        
066        /**
067         * Creates a new minimal bearer access token with a randomly generated 
068         * 256-bit (32-byte) value, Base64URL-encoded. The optional lifetime 
069         * and scope are left undefined.
070         */
071        public BearerAccessToken() {
072        
073                this(32);
074        }       
075
076
077        /**
078         * Creates a new minimal bearer access token with a randomly generated 
079         * value of the specified byte length, Base64URL-encoded. The optional 
080         * lifetime and scope are left undefined.
081         *
082         * @param byteLength The byte length of the value to generate. Must be
083         *                   greater than one.
084         */
085        public BearerAccessToken(final int byteLength) {
086        
087                this(byteLength, 0L, null);
088        }
089
090
091        /**
092         * Creates a new bearer access token with a randomly generated 256-bit 
093         * (32-byte) value, Base64URL-encoded.
094         *
095         * @param lifetime The lifetime in seconds, 0 if not specified.
096         * @param scope    The scope, {@code null} if not specified.
097         */
098        public BearerAccessToken(final long lifetime, final Scope scope) {
099        
100                this(32, lifetime, scope);
101        }
102
103
104        /**
105         * Creates a new bearer access token with a randomly generated value of 
106         * the specified byte length, Base64URL-encoded.
107         *
108         * @param byteLength The byte length of the value to generate. Must be
109         *                   greater than one.
110         * @param lifetime   The lifetime in seconds, 0 if not specified.
111         * @param scope      The scope, {@code null} if not specified.
112         */
113        public BearerAccessToken(final int byteLength, final long lifetime, final Scope scope) {
114        
115                super(AccessTokenType.BEARER, byteLength, lifetime, scope);
116        }
117        
118        
119        /**
120         * Creates a new minimal bearer access token with the specified value.
121         * The optional lifetime and scope are left undefined.
122         *
123         * @param value The access token value. Must not be {@code null} or
124         *              empty string.
125         */
126        public BearerAccessToken(final String value) {
127        
128                this(value, 0L, null);
129        }
130        
131        
132        /**
133         * Creates a new bearer access token with the specified value and 
134         * optional lifetime and scope.
135         *
136         * @param value    The access token value. Must not be {@code null} or
137         *                 empty string.
138         * @param lifetime The lifetime in seconds, 0 if not specified.
139         * @param scope    The scope, {@code null} if not specified.
140         */
141        public BearerAccessToken(final String value, final long lifetime, final Scope scope) {
142        
143                super(AccessTokenType.BEARER, value, lifetime, scope);
144        }
145        
146        
147        /**
148         * Returns the HTTP Authorization header value for this bearer access 
149         * token.
150         *
151         * <p>Example:
152         *
153         * <pre>
154         * Authorization: Bearer eyJhbGciOiJIUzI1NiJ9
155         * </pre>
156         *
157         * @return The HTTP Authorization header.
158         */
159        @Override
160        public String toAuthorizationHeader(){
161        
162                return "Bearer " + getValue();
163        }
164        
165        
166        @Override
167        public boolean equals(final Object object) {
168        
169                return object instanceof BearerAccessToken &&
170                       this.toString().equals(object.toString());
171        }
172
173
174        /**
175         * Parses a bearer access token from a JSON object access token 
176         * response.
177         *
178         * @param jsonObject The JSON object to parse. Must not be 
179         *                   {@code null}.
180         *
181         * @return The bearer access token.
182         *
183         * @throws ParseException If the JSON object couldn't be parsed to a
184         *                        bearer access token.
185         */
186        public static BearerAccessToken parse(final JSONObject jsonObject)
187                throws ParseException {
188                
189                AccessTokenUtils.parseAndEnsureType(jsonObject, AccessTokenType.BEARER);
190                String accessTokenValue = AccessTokenUtils.parseValue(jsonObject);
191                long lifetime = AccessTokenUtils.parseLifetime(jsonObject);
192                Scope scope = AccessTokenUtils.parseScope(jsonObject);
193                return new BearerAccessToken(accessTokenValue, lifetime, scope);
194        }
195        
196        
197        /**
198         * Parses an HTTP Authorization header for a bearer access token.
199         *
200         * @param header The HTTP Authorization header value to parse. May be
201         *               {@code null} if the header is missing, in which case
202         *               an exception will be thrown.
203         *
204         * @return The bearer access token.
205         *
206         * @throws ParseException If the HTTP Authorization header value 
207         *                        couldn't be parsed to a bearer access token.
208         */
209        public static BearerAccessToken parse(final String header)
210                throws ParseException {
211                
212                return new BearerAccessToken(AccessTokenUtils.parseValueFromHeader(header, AccessTokenType.BEARER));
213        }
214        
215        
216        /**
217         * Parses a query or form parameters map for a bearer access token.
218         *
219         * @param parameters The query parameters. Must not be {@code null}.
220         *
221         * @return The bearer access token.
222         *
223         * @throws ParseException If a bearer access token wasn't found in the
224         *                        parameters.
225         */
226        public static BearerAccessToken parse(final Map<String,List<String>> parameters)
227                throws ParseException {
228                
229                return new BearerAccessToken(AccessTokenUtils.parseValueFromQueryParameters(parameters, AccessTokenType.BEARER));
230        }
231        
232        
233        
234        /**
235         * Parses an HTTP request for a bearer access token.
236         * 
237         * @param request The HTTP request to parse. Must not be {@code null}.
238         * 
239         * @return The bearer access token.
240         * 
241         * @throws ParseException If a bearer access token wasn't found in the
242         *                        HTTP request.
243         */
244        public static BearerAccessToken parse(final HTTPRequest request)
245                throws ParseException {
246
247                // See http://tools.ietf.org/html/rfc6750#section-2
248                String authzHeader = request.getAuthorization();
249
250                if (authzHeader != null) {
251                        return parse(authzHeader);
252                }
253
254                // Try alternative token locations, form and query string are
255                // parameters are not differentiated here
256                Map<String,List<String>> params = request.getQueryParameters();
257                return parse(params);
258        }
259}