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.openid.connect.sdk;
019
020
021import java.net.URI;
022
023import net.jcip.annotations.Immutable;
024
025import com.nimbusds.common.contenttype.ContentType;
026import com.nimbusds.oauth2.sdk.ParseException;
027import com.nimbusds.oauth2.sdk.ProtectedResourceRequest;
028import com.nimbusds.oauth2.sdk.SerializeException;
029import com.nimbusds.oauth2.sdk.http.HTTPRequest;
030import com.nimbusds.oauth2.sdk.token.BearerAccessToken;
031
032
033/**
034 * UserInfo request. Used to retrieve the consented claims about the end-user.
035 *
036 * <p>Example HTTP GET request:
037 *
038 * <pre>
039 * GET /userinfo HTTP/1.1
040 * Host: server.example.com
041 * Authorization: Bearer SlAV32hkKG
042 * </pre>
043 *
044 * <p>Related specifications:
045 *
046 * <ul>
047 *     <li>OpenID Connect Core 1.0, section 5.3.1.
048 *     <li>OAuth 2.0 Bearer Token Usage (RFC6750), section 2.
049 * </ul>
050 */
051@Immutable
052public class UserInfoRequest extends ProtectedResourceRequest {
053
054
055        /**
056         * The HTTP method.
057         */
058        private final HTTPRequest.Method httpMethod;
059        
060        
061        /**
062         * Creates a new UserInfo HTTP GET request.
063         *
064         * @param uri         The URI of the UserInfo endpoint. May be
065         *                    {@code null} if the {@link #toHTTPRequest} method
066         *                    will not be used.
067         * @param accessToken An OAuth 2.0 Bearer access token for the request.
068         *                    Must not be {@code null}.
069         */
070        public UserInfoRequest(final URI uri, final BearerAccessToken accessToken) {
071        
072                this(uri, HTTPRequest.Method.GET, accessToken);
073        }
074        
075        
076        /**
077         * Creates a new UserInfo request.
078         *
079         * @param uri         The URI of the UserInfo endpoint. May be
080         *                    {@code null} if the {@link #toHTTPRequest} method
081         *                    will not be used.
082         * @param httpMethod  The HTTP method. Must be HTTP GET or POST and not 
083         *                    {@code null}.
084         * @param accessToken An OAuth 2.0 Bearer access token for the request.
085         *                    Must not be {@code null}.
086         */
087        public UserInfoRequest(final URI uri, final HTTPRequest.Method httpMethod, final BearerAccessToken accessToken) {
088        
089                super(uri, accessToken);
090                
091                if (httpMethod == null)
092                        throw new IllegalArgumentException("The HTTP method must not be null");
093                
094                this.httpMethod = httpMethod;
095                
096                
097                if (accessToken == null)
098                        throw new IllegalArgumentException("The access token must not be null");
099        }
100        
101        
102        /**
103         * Gets the HTTP method for this UserInfo request.
104         *
105         * @return The HTTP method.
106         */
107        public HTTPRequest.Method getMethod() {
108        
109                return httpMethod;
110        }
111        
112        
113        @Override
114        public HTTPRequest toHTTPRequest() {
115                
116                if (getEndpointURI() == null)
117                        throw new SerializeException("The endpoint URI is not specified");
118
119                HTTPRequest httpRequest = new HTTPRequest(httpMethod, getEndpointURI());
120                
121                switch (httpMethod) {
122                
123                        case GET:
124                                httpRequest.setAuthorization(getAccessToken().toAuthorizationHeader());
125                                break;
126                                
127                        case POST:
128                                httpRequest.setEntityContentType(ContentType.APPLICATION_URLENCODED);
129                                httpRequest.setQuery("access_token=" + getAccessToken().getValue());
130                                break;
131                        
132                        default:
133                                throw new SerializeException("Unexpected HTTP method: " + httpMethod);
134                }
135                
136                return httpRequest;
137        }
138        
139        
140        /**
141         * Parses the specified HTTP request for a UserInfo request.
142         *
143         * @param httpRequest The HTTP request. Must not be {@code null}.
144         *
145         * @return The UserInfo request.
146         *
147         * @throws ParseException If the HTTP request couldn't be parsed to a 
148         *                        UserInfo request.
149         */
150        public static UserInfoRequest parse(final HTTPRequest httpRequest)
151                throws ParseException {
152                
153                return new UserInfoRequest(
154                        httpRequest.getURI(),
155                        httpRequest.getMethod(),
156                        BearerAccessToken.parse(httpRequest)
157                );
158        }
159}