001/*
002 * Copyright 2012-2016 UnboundID Corp.
003 *
004 * This program is free software; you can redistribute it and/or modify
005 * it under the terms of the GNU General Public License (GPLv2 only)
006 * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
007 * as published by the Free Software Foundation.
008 *
009 * This program is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
012 * GNU General Public License for more details.
013 *
014 * You should have received a copy of the GNU General Public License
015 * along with this program; if not, see <http://www.gnu.org/licenses>.
016 */
017
018package com.unboundid.scim.sdk;
019
020/**
021 * This class defines the validation status of a OAuth 2.0 bearer token, and
022 * allows a OAuthTokenHandler extension to insert an error description and
023 * OAuth scope value to be returned to the client.
024 */
025public final class OAuthTokenStatus
026{
027  /**
028   * Possible values for the error_code.
029   */
030  public static enum ErrorCode
031  {
032    /**
033     * Indicates that the OAuth token is valid.
034     */
035    OK(200),
036
037    /**
038     * Indicates that the OAuth token is expired, revoked, malformed, or invalid
039     * for other reasons.
040     */
041    INVALID_TOKEN(401),
042
043    /**
044     * Indicates that the request requires higher privileges than provided by
045     * the OAuth token.
046     */
047    INSUFFICIENT_SCOPE(403);
048
049
050    private final int code;
051
052    /**
053     * Creates an ErrorCode instance with the given HTTP status code.
054     *
055     * @param code The HTTP status code.
056     */
057    ErrorCode(final int code)
058    {
059      this.code = code;
060    }
061
062    /**
063     * Get the HTTP status code associated with this ErrorCode.
064     *
065     * @return the integer HTTP status code for this ErrorCode.
066     */
067    public int getHttpStatusCode()
068    {
069      return code;
070    }
071  }
072
073  private final ErrorCode code;
074  private final String description;
075  private final String scope;
076
077  /**
078   * Constructs an OAuthTokenStatus with the given ErrorCode.
079   *
080   * @param errorCode the {@link ErrorCode} to use. This must not be
081   *                  {@code null}.
082   */
083  public OAuthTokenStatus(final ErrorCode errorCode)
084  {
085    this(errorCode, null, null);
086  }
087
088  /**
089   * Constructs an OAuthTokenStatus with the given ErrorCode and error
090   * description.
091   *
092   * @param errorCode the {@link ErrorCode} to use. This must not be
093   *                  {@code null}.
094   * @param errorDescription a human-readable description of the error. This may
095   *                         be {@code null}.
096   */
097  public OAuthTokenStatus(final ErrorCode errorCode,
098                          final String errorDescription)
099  {
100    this(errorCode, errorDescription, null);
101  }
102
103  /**
104   * Constructs an OAuthTokenStatus with the given ErrorCode, error
105   * description, and scope value.
106   *
107   * @param errorCode the {@link ErrorCode} to use. This must not be
108   *                  {@code null}.
109   * @param errorDescription a human-readable description of the error. This may
110   *                         be {@code null}.
111   * @param scope a space-delimited list of case-sensitive scope values
112   *              indicating the required scope of the access token for
113   *              accessing the requested resource. Scope values are
114   *              implementation defined; there is no centralized registry for
115   *              them; allowed values are defined by the authorization server.
116   *              The order of scope values is not significant. This may be
117   *              {@code null}.
118   */
119  public OAuthTokenStatus(final ErrorCode errorCode,
120                          final String errorDescription,
121                          final String scope)
122  {
123    if(errorCode == null)
124    {
125      throw new NullPointerException("The errorCode parameter may not be null");
126    }
127    this.code = errorCode;
128    this.description = errorDescription;
129    this.scope = scope;
130  }
131
132  /**
133   * Gets the specified ErrorCode for this OAuthTokenStatus.
134   *
135   * @return an {@link ErrorCode} instance.
136   */
137  public ErrorCode getErrorCode()
138  {
139    return code;
140  }
141
142  /**
143   * Gets the specified error description for this OAuthTokenStatus.
144   *
145   * @return a human-readable explanation of the error condition, or
146   *         {@code null} if none was specified.
147   */
148  public String getErrorDescription()
149  {
150    return description;
151  }
152
153  /**
154   * Gets the specified OAuth scope for this OAuthTokenStatus.
155   *
156   * @return a space-delimited list of case-sensitive scope values indicating
157   *         the required scope of the access token for accessing the requested
158   *         resource. Scope values are implementation defined; there is no
159   *         centralized registry for them; allowed values are defined by the
160   *         authorization server. The order of scope values is not significant.
161   *         This may return {@code null} if no scope was specified.
162   */
163  public String getScope()
164  {
165    return scope;
166  }
167}