001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at
010 * docs/licenses/cddl.txt
011 * or http://www.opensource.org/licenses/cddl1.php.
012 * See the License for the specific language governing permissions
013 * and limitations under the License.
014 *
015 * When distributing Covered Code, include this CDDL HEADER in each
016 * file and include the License file at
017 * docs/licenses/cddl.txt.  If applicable,
018 * add the following below this CDDL HEADER, with the fields enclosed
019 * by brackets "[]" replaced with your own identifying information:
020 *      Portions Copyright [yyyy] [name of copyright owner]
021 *
022 * CDDL HEADER END
023 *
024 *
025 *      Copyright 2016-2019 Ping Identity Corporation
026 */
027
028
029package com.unboundid.directory.sdk.broker.api;
030
031import com.unboundid.directory.sdk.broker.internal.BrokerExtension;
032import com.unboundid.directory.sdk.broker.types.TokenValidationResult;
033import com.unboundid.directory.sdk.common.api.AbstractAccessTokenValidator;
034import com.unboundid.util.Extensible;
035import com.unboundid.util.ThreadSafety;
036import com.unboundid.util.ThreadSafetyLevel;
037
038/**
039 * This class defines an API that may be implemented by Data Governance Server
040 * extensions that validate externally generated access tokens.  Implementing
041 * extensions that support this API enables the Data Governance Server
042 * to accept access tokens generated from external Identity Providers.
043 *
044 * <H2>Configuring Access Token Validators</H2>
045 * In order to configure an Access Token Validator created using this API, use
046 * a command like:
047 * <PRE>
048 *      dsconfig create-token-validator \
049 *           ---validator-name "<I>{name}</I>" \
050 *           --type third-party \
051 *           --set "extension-class:<I>{class-name}</I>" \
052 *           --set "extension-argument:<I>{name=value}</I>"
053 * </PRE>
054 * where "<I>{name}</I>" is the name to use for the Access Token Validator
055 * instance, "<I>{class-name}</I>" is the fully-qualified name of the Java class
056 * that extends
057 * {@code com.unboundid.directory.sdk.broker.api.AccessTokenValidator},
058 * and "<I>{name=value}</I>" represents name-value pairs for any arguments to
059 * provide to the Access Token Validator. If multiple arguments should be
060 * provided to the extension, then the
061 * "<CODE>--set extension-argument:<I>{name=value}</I></CODE>" option should be
062 * provided multiple times.
063 */
064@Extensible()
065@BrokerExtension
066@ThreadSafety(level= ThreadSafetyLevel.INTERFACE_THREADSAFE)
067public abstract class AccessTokenValidator
068    extends AbstractAccessTokenValidator
069{
070  // No implementation necessary. This class is in this package so it is
071  // bundled with the Data Governance Server SDK.
072
073  /**
074   * Validate the provided access token.
075   * @param encodedAccessToken access token string as it is received from the
076   *                           requesting client.
077   * @return The Data Governance Server may be configured to accept access tokens
078   * from multiple sources so it is important that each validator differentiate
079   * between a token format that it does not recognize and a token that it can
080   * process but is not valid.
081   *
082   * If the token can be processed, the validator must return a
083   * TokenValidationResult object containing token properties.  Most
084   * importantly the {@code active} field of the TokenValidationResult must be
085   * set by the validator.
086   *
087   * The decision as to whether an access token is accepted or not is made by
088   * the Data Governance Server's policy engine.  All properties of the
089   * TokenValidationResult are available to XACML policies, however it is
090   * possible that policies may only examine a subset of those properties.
091   * When writing a new validator it is important to match up the properties
092   * exposed by the validator with the properties consulted by the default
093   * and/or custom policies.
094   *
095   * If the token cannot be introspected by the Access Token Validator it must
096   * return null to allow other validators to have a chance to process the
097   * token.
098   *
099   * @throws Exception if an error occurs during the processing of a token
100   * that can be introspected by the validator.  Exceptions should only be
101   * thrown for unexpected internal errors.   Sensitive information should not
102   * be included in the exception message as the message may be returned to
103   * the client application that has passed the token.
104   */
105  public abstract TokenValidationResult validate(
106      final String encodedAccessToken) throws Exception;
107}