Gestión de proveedores de OAuth
EMPRESA Esta es una característica de EJBCA Enterprise.
A continuación, se proporcionan flujos de trabajo e instrucciones para administrar proveedores de OAuth en EJBCA.
Para obtener más información conceptual sobre los proveedores de OAuth, consulte Descripción general de los proveedores de OAuth .
Prerrequisitos
Dado que la autenticación OAuth funciona redirigiendo al usuario al proveedor externo y luego de vuelta a EJBCA, el nombre de host visible externamente (y el puerto HTTPS) deben estar configurados correctamente. Esto se puede configurar en conf/web.properties, con las propiedades httpsserver.hostname y httpserver.pubhttps . Para obtener más información sobre las propiedades, consulte " Administración de configuraciones de EJBCA" .
Configuración de proveedores de OAuth en la interfaz de usuario de CA
Los proveedores de OAuth se configuran en la pestaña Proveedores de OAuth confiables de configuración del sistema ( UI de CA → Configuración del sistema → Proveedores de OAuth confiables ).
El La pestaña " Proveedores OAuth de Confianza" muestra una lista de los proveedores configurados. La interfaz de usuario también permite agregar, editar y eliminar proveedores OAuth, así como establecer un proveedor de confianza predeterminado. Tenga en cuenta que solo los administradores con acceso root pueden ver y acceder a la pestaña "Proveedores OAuth de Confianza" .
Agregar un proveedor OAuth confiable
Para agregar un nuevo proveedor OAuth:
Seleccione Configuración del sistema → Proveedores OAuth confiables .
Haga clic en Agregar en la parte inferior de la página para ver la página Agregar proveedor OAuth confiable con los campos obligatorios y opcionales del proveedor.
Especifique los campos de acuerdo a lo siguiente:
Tipo de proveedor OAuth: Seleccione el tipo de proveedor. Los tipos admitidos actualmente son genérico, Azure, PingID y Keycloak.
Nombre del proveedor OAuth: Especifique una etiqueta única para el proveedor. Obligatorio para todos los proveedores.
URL: Establezca la URL de inicio de sesión base para el proveedor. Para Azure, podría ser https://login.microsoftonline.com . Para pruebas locales con Keycloak, se puede configurar como http://localhost:8084/auth . Este campo no aparece para el ID de ping.
URL de autorización: Establezca la URL del punto final de autorización del proveedor. Para el ID de ping, el valor de este campo se encuentra en la pestaña Configuración de la aplicación (en Conexiones / Aplicaciones ).
URL del token: Establezca la URL del punto final del token para el proveedor. Para el ID de ping, el valor de este campo se encuentra en la pestaña Configuración de su aplicación (en Conexiones / Aplicaciones ).
URL de cierre de sesión: Establezca la URL del punto final de cierre de sesión del proveedor. Para el ID de ping, el valor de este campo se encuentra en la pestaña Configuración de su aplicación (en Conexiones / Aplicaciones ).
Límite de sesgo (ms): Establezca un límite de sesgo en milisegundos. El límite de sesgo predeterminado es 1 minuto, pero puede configurarse en un entero arbitrario no negativo.
Audiencia: Establezca el valor de audiencia esperado. La audiencia debe ser igual al valor aud en el token JSON de este proveedor. Este valor indica que el token de inicio de sesión está destinado a ser utilizado por EJBCA. Para obtener más información sobre la finalidad de una reclamación de audiencia y cómo configurarla, consulte Configuración de reclamaciones de audiencia .
Desactivar comprobación de audiencia: Seleccione esta opción para admitir proveedores de OAuth que no admiten notificaciones de audiencia, como PingID. Desactivar esta comprobación tiene implicaciones de seguridad y no se recomienda. Consulte "Configurar notificaciones de audiencia" para obtener más información.
Nombre del cliente: especifique el campo "Cliente". Obligatorio para Azure, ID de ping y Keycloak.
Secreto de cliente: Ingrese el secreto de cliente. Obligatorio para proveedores de Azure y Ping ID.
Método de entrada de clave pública: Elija cómo se proporcionará la clave pública. Las opciones son: Carga de archivo, Valor de texto y URL de configuración.
Identificador de clave OAuth: Especifique un identificador de clave OAuth usando cualquier cadena arbitraria. El identificador de clave OAuth debe ser único y no puede usar el mismo identificador que ninguna clave pública de este o cualquier otro proveedor existente. El identificador de clave OAuth debe ser igual al valor de "kid" en el token JSON de este proveedor.
Subir clave pública: Agrega la clave pública al proveedor. Se puede agregar más de una clave si es necesario. Cada proveedor debe tener al menos una clave pública para funcionar correctamente.
Haga clic en Agregar para agregar el proveedor OAuth confiable.
Además de los campos anteriores, también hay algunos campos exclusivos para ciertos tipos de proveedores.
Los proveedores de Azure tienen los siguientes campos adicionales:
Inquilino: especifique el inquilino del proveedor.
Ámbito: Establezca el ámbito. En Azure Active Directory, esto se puede configurar en Exponer una API → Agregar un ámbito .
Los proveedores de Keycloak tienen el campo adicional:
Dominio: Introduzca el nombre del dominio. Este corresponde al dominio de Keycloak configurado.
La pestaña Proveedores de OAuth de confianza muestra todos los proveedores existentes, con su nombre y URL. El botón "Ver" junto a un proveedor abre una vista más detallada de sus campos.
Edición de un proveedor OAuth de confianza
El botón Editar permite al administrador editar todos los campos de configuración. Al igual que al añadir un nuevo proveedor, la interfaz de usuario no permite identificadores de clave duplicados. Para eliminar un proveedor, haga clic en Eliminar.
La opción "Proveedor OAuth de confianza predeterminado" permite configurar un proveedor predeterminado. De forma predeterminada, ningún proveedor está configurado como predeterminado.
Configuración de proveedores OAuth en la interfaz de línea de comandos
Los proveedores de OAuth también se pueden configurar mediante el script ejbca.sh de la línea de comandos. Este script se encuentra en la carpeta bin del código fuente de instalación de EJBCA. Consulte la Interfaz de línea de comandos local (CLI de EJBCA) para obtener más información.
Para configurar proveedores OAuth confiables mediante la línea de comando ejbca.sh, haga lo siguiente:
Ejecute el siguiente comando para mostrar las subcategorías disponibles para el comando de configuración:
. /ejbca .sh configLa salida enumera las subcategorías disponibles, incluido oauth:
The following subcategories are available for the command 'config' :[ cmp | est | oauth | protocols | scep ]--------------------------------And the following commands are available:dump Shows the current server configurationType a command and "--help" for more information.A continuación, emita el subcomando oauth para enumerar todas las opciones disponibles:
bin /ejbca .sh config oauth--------------------------------The following commands are available:addoauthprovider Adds a new Trusted OAuth Provider to the list of available providers.editoauthprovider Edit key identifier, public key and /or skew limit for an existing Trusted OAuth Provider.listoauthproviders Lists the current oauth providers available in EJBCAoauthproviderkey Adds or removes public key of Trusted OAuth Provider with defined label.removeoauthprovider Remove an existing Trusted OAuth Provider from the list of keys.setdefaultoauthprovider Sets one of the existing Trusted OAuth Providers as default.viewoauthprovider Displays information about the specified Trusted OAuth Provider available in EJBCAType a command and "--help" for more information.Los comandos enumerados se pueden utilizar para agregar, editar y enumerar proveedores OAuth existentes, así como para eliminar o configurar un proveedor OAuth predeterminado.
A continuación, se describe cómo agregar y editar un proveedor OAuth de confianza mediante la línea de comandos. Para obtener más información sobre el uso de otros comandos OAuth, ejecute oauth --help .
Agregar un proveedor OAuth confiable
Para enumerar todos los parámetros obligatorios disponibles para el comando addoauthprovider , ejecute lo siguiente:
ejbca.sh config oauth addoauthprovider --help Esto genera una lista de parámetros obligatorios y opcionales para el comando addoauthprovider . Tenga en cuenta que, según el tipo de proveedor, algunos de los parámetros opcionales podrían ser obligatorios.
Mandatory parameters:--audience <AUDIENCE> (Switch is not required)Expected value in la reclamación del token 's ' aud' claim.--label <PROVIDER_NAME> (Switch is not required)Trusted OAuth Provider name.--skewlimit <SKEW_LIMIT> (Switch is not required)Skew limit to be used.-- type <PROVIDER_TYPE.> (Switch is not required)Type of the Trusted OAuth Provider. Supported types are GENERIC, PINGID, KEYCLOAK andAZURE.Optional parameters:--client <CLIENT_NAME> (Switch is not required)Client name for EJBCA in Trusted OAuth Provider.--clientsecret <CLIENT_SECRET> (Switch is not required)Client secret in Trusted OAuth Provider.--clipassword <CLI_PASSWORD>Set the CLI user's password explicitly on the línea command line with--clipassword=<password>--logouturl <PROVIDER_LOGOUT_URL> (Switch is not required)logout Trusted OAuth Provider endpoint URL.--realm <REALM /TENANT_NAME > (Switch is not required)Trusted OAuth Provider realm name.--scope <SCOPE> (Switch is not required)Trusted OAuth Provider scope. Used for Azure Trusted OAuth Providers.--tokenurl <PROVIDER_TOKEN_URL> (Switch is not required)Trusted OAuth Provider token endpoint URL.--url <PROVIDER_URL> (Switch is not required)Trusted OAuth Provider authorization endpoint URL.El parámetro de tipo determina si el proveedor configurado es de tipo no especificado (genérico), Keycloak, ID de ping o Azure. Los campos obligatorios varían según el tipo de proveedor. Si no se especifica un parámetro obligatorio específico del tipo, la salida del comando contendrá un error que indicará qué parámetro falta.
Para los proveedores de Azure, los parámetros obligatorios específicos del tipo son: URL del proveedor ( --url ), inquilino ( --realm ), ámbito ( --scope ), nombre del cliente ( --client ) y secreto del cliente ( --clientsecret ). Tenga en cuenta que la clave de cifrado para el secreto del cliente para el almacenamiento debe proporcionarse en cesecore.properties como password.encryption.key, ya que confiar en la clave predeterminada no es seguro.
Para los proveedores de Keycloak, los parámetros obligatorios específicos del tipo son URL del proveedor ( --url ), dominio ( –realm ) y nombre del cliente ( –client ).
Para los proveedores de ID de ping, los parámetros obligatorios específicos del tipo son la URL de autorización ( --url ), la URL del token ( --tokenurl ), la URL de cierre de sesión ( --logouturl ), el nombre del cliente ( --client ) y el secreto del cliente ( --clientsecret ).
La etiqueta del proveedor debe ser única. Si no lo es, se mostrará un error:
Trusted OAuth Provider with the same label already exists!El formato skewlimit debe tener un valor entero no negativo.
El límite de sesgo es el valor (en milisegundos) utilizado para permitir una pequeña diferencia de tiempo (normalmente menos de 10 minutos) entre los sistemas (por ejemplo, EJBCA y el proveedor OAuth).
Para agregar un proveedor OAuth, ejecute el comando addoauthprovider según el siguiente ejemplo:
bin /ejbca .sh config oauth addoauthprovider --label testlabel --skewlimit 50000 -- type keycloak --url testurl --client testclient --realm testrealm --audience audienceA continuación se muestra la salida exitosa del comando anterior:
Trusted OAuth Provider with label testlabel added successfully!El parámetro keyidentifier es una identificación única que se utiliza como identificación externa que se muestra en la CLI y la GUI para el proveedor agregado.
El ID debe ser único y si intenta utilizar un ID ya existente, obtendrá un error similar al siguiente:
Trusted OAuth Provider with same kid or internal Id exists!El formato skewlimit debe tener un valor entero no negativo.
El límite de sesgo es el valor (en milisegundos) utilizado para permitir una diferencia de tiempo menor (generalmente menos de 10 minutos) entre los sistemas (por ejemplo, EJBCA y el proveedor OAuth).
Para agregar un proveedor OAuth, ejecute el comando addoauthprovider según el siguiente ejemplo:
bin/ejbca.sh config oauth addoauthprovider --keyidentifier test --publickey pubkey.pem --skewlimit 1500 --audience audienceA continuación se muestra la salida exitosa del comando anterior:
Trusted OAuth Provider with kid: test added successfully!Una vez que haya agregado el proveedor, ejecute lo siguiente para enumerar los proveedores disponibles:
bin /ejbca .sh config oauth listoauthprovidersLa salida muestra al proveedor con la prueba de identificador de clave y skewlimit establecido en 1500 milisegundos:
Kid: test | skew limit: 1500 | publickey fingerprint: mb93lXyccgohbB2ze4x2zXHr5ep84MCZvcqHM0HN0Ts= Agregar claves públicas a un proveedor OAuth confiable
Un proveedor configurado necesita una clave pública para funcionar. El comando oauthproviderkey se utiliza para añadir una clave pública a un proveedor existente. El parámetro de etiqueta ( --label ) es obligatorio y determina el proveedor con el que se operará. Se pueden añadir más de uno si es necesario y también se pueden eliminar las claves públicas (use --action remove ).
Al agregar una clave, se debe configurar el parámetro keymethod . La clave pública se puede agregar desde un archivo ( --keymethod file ), desde un texto ( --keymethod text ) o proporcionando una URL de configuración ( --keymethod url ). El archivo de clave pública, el texto y la URL de configuración se pueden especificar mediante los parámetros --keyfile , --key y --keyurl, respectivamente.
Los archivos de clave deben contener una clave pública en formato PEM, DER o JWK, o un certificado X.509 en formato PEM o DER. Cuando las claves se proporcionan como texto, deben usar el formato PEM, DER o JWK, o estar codificadas en Base64.
También se necesita un identificador de clave para la clave pública. Los identificadores de clave deben ser únicos en todas las claves públicas de todos los proveedores de OAuth de confianza. Si se añade un duplicado, se mostrará un error.
A continuación se muestra un comando de ejemplo:
bin /ejbca .sh config oauth oauthproviderkey --label testlabel --action add --keymethod file --keyfile public.pem --keyidentifier testkeyidLa ejecución exitosa del comando se confirma mediante el siguiente resultado:
Public key successfuly added to Trusted OAuth Provider with label testlabel! Visualización de un proveedor OAuth confiable
El comando viewoauthprovider permite ver información detallada sobre un único proveedor (para obtener una visión general de todos los proveedores, consulte listoauthproviders ). Se muestran todos los campos del proveedor, excepto el campo "Secreto de cliente".
El comando se puede utilizar de la siguiente manera:
bin /ejbca .sh config oauth viewoauthprovider --label test Edición de un proveedor OAuth de confianza
El comando editoauthprovider se utiliza para editar un proveedor de confianza existente.
Ejecute lo siguiente para enumerar los parámetros del comando editoauthprovider para el proveedor dado (prueba):
bin /ejbca .sh config oauth editoauthprovider --keyidentifier test --helpLa salida enumera y explica los parámetros obligatorios y opcionales del comando.
Mandatory parameters:--label <LABEL> (Switch is not required)Label of the Trusted OAuth Provider to update its parameters.Optional parameters:--new-client <CLIENT_NAME> (Switch is not required)Updated Client Name.--new-audience <AUDIENCE> (Switch is not required)New Audience.--new-clientsecret <CLIENT_SECRET> (Switch is not required)Updated Client Secret.--new-label <PROVIDER_NAME> (Switch is not required)Updated Provider Label.--new-logouturl <PROVIDER_LOGOUT_URL> (Switch is not required)New logout endpoint URL.--new-realm <REALM/TENANT_NAME> (Switch is not required)Updated Realm/Tenant name.--new-scope <SCOPE> (Switch is not required)Updated Scope.--new-skewlimit <SKEW_LIMIT> (Switch is not required)Updated Skew Limit.--new-tokenurl <PROVIDER_TOKEN_URL> (Switch is not required)New token endpoint URL.--new-url <PROVIDER_URL> (Switch is not required)Updated URL to the login page.