Assinatura de tokens

Todo token que o Authio emite é um JWT assinado. Um client tem duas configurações de assinatura: uma para o que só o seu app lê (o ID token, a resposta assinada do UserInfo e o logout token do back-channel) e outra para o access token que as suas APIs leem. O refresh token não segue nenhuma das duas: o Authio sempre o assina com a própria chave. Para tokens que ninguém fora do app deve ler, veja Tokens criptografados.

As duas configurações

Em Clients, abra o client e vá em Editar → Segurança → Configuração de tokens. Cada configuração aceita RS, PS ou ES (assimétricos, verificados com as chaves públicas do realm) ou HS (HMAC, com o client secret como chave), em 256, 384 ou 512 bits.

Quando usar HS256

O HMAC serve para um client confidencial cujos tokens só são lidos pelo próprio app e pela própria API, que já têm o client secret: eles verificam os tokens sem buscar um JWKS nem guardar chaves em cache. Em qualquer outro caso, prefira um algoritmo assimétrico: qualquer um verifica com a chave pública, nada secreto é compartilhado, e quem consegue verificar um token não consegue também assinar um.

O que o Authio aceita

Uma recusa aponta o campo com problema em notifications: clientConfiguration.clientTokenConfiguration.idTokenSigningAlgorithmType para um client público pedindo HS no ID token, clientConfiguration.clientTokenConfiguration.idTokenSigningAlgorithm para um secret curto demais para ele, e clientConfiguration.clientTokenConfiguration.accessTokenSigningAlgorithm para tudo o que diz respeito ao access token, inclusive dois algoritmos assimétricos diferentes.

Na Admin API

As configurações ficam em clientConfiguration.clientTokenConfiguration. algorithmJwsType agora é idTokenSigningAlgorithmType e digitalSubscriptionsAlgorithm agora é idTokenSigningAlgorithm, sem alias; accessTokenSigningAlgorithm é novo e aceita os mesmos valores. Na criação ele é opcional (omitido, vale o padrão acima); na atualização, omiti-lo mantém o algoritmo atual.

{
  "clientConfiguration": {
    "clientTokenConfiguration": {
      "idTokenSigningAlgorithmType": "HMAC",
      "idTokenSigningAlgorithm": "HmacSha256",
      "accessTokenSigningAlgorithm": "RsaSsaPssSha256"
    }
  }
}

APIs, resource servers e servidores MCP

Um access token assinado com HS não tem chave no JWKS do realm. A API do próprio client tem o client secret e o valida localmente; qualquer outra API (a de um terceiro, um resource server do realm, um servidor MCP) não tem o secret e precisa validar o token por introspecção, como o client de introspecção do resource server.

Ou assine o access token do client com RS, PS ou ES, ou configure esses servidores para validar só por introspecção:

import { authioBearer } from '@hyper.authio/express'

app.use(
  '/api',
  authioBearer({
    issuer: process.env.AUTHIO_ISSUER!,
    audiences: 'https://orders.example.com',
    introspection: 'introspectionOnly',
    client: { clientId: 'orders-api', clientSecret: process.env.ORDERS_API_SECRET! },
  }),
)

O client em cada um deles é o client confidencial do próprio servidor, escolhido como Client de introspecção do resource server: o Authio informa que um token endereçado a um resource server está ativo só para esse client.

Configure o seu app e a sua API

As bibliotecas do Authio espelham o client: cada configuração é uma opção, e uma opção omitida fica desligada. Sem uma opção de assinatura, a biblioteca aceita só os algoritmos assimétricos que o realm publica, e recusa um token HS com invalid_algorithm, apontando a opção ou a introspecção. Com um algoritmo HS informado, ela verifica com o client secret, que precisa respeitar o mesmo tamanho mínimo de cima.

Node.js

No @hyper.authio/client e no @hyper.authio/bff 0.8.0, idTokenSignedResponseAlg cobre o ID token e o logout token, e userinfoSignedResponseAlg o UserInfo assinado, que segue idTokenSignedResponseAlg quando omitido. No @hyper.authio/server e no @hyper.authio/express, accessTokenSignedResponseAlg (um algoritmo ou vários) verifica HS com o clientSecret de client: { clientId, clientSecret }.

import { createAuthioClient } from '@hyper.authio/client'

export const authio = createAuthioClient({
  issuer: process.env.AUTHIO_ISSUER!,
  clientId: 'storefront',
  clientSecret: process.env.AUTHIO_CLIENT_SECRET!,
  checks: ['pkce', 'state', 'nonce'],
  codeChallengeMethod: 'S256',
  idTokenSignedResponseAlg: 'HS256',
  redirectUri: 'https://shop.example.com/callback',
})

Sem resource, o aud do access token é a audiência configurada no client (Authio, a menos que você tenha mudado). Qualquer outra API valida por introspecção, como mostrado acima.

.NET

O Authio.Client, o Authio.AspNetCore e o Authio.AspNetCore.Bff 0.8.0 leem IdTokenSignedResponseAlg, UserinfoSignedResponseAlg (omitido, vale o do ID token) e AccessTokenSignedResponseAlg (um valor ou uma lista) da seção Authio. O HS é verificado com o ClientSecret, em bytes UTF-8.

{
  "Authio": {
    "Authority": "https://authio.api.hyperio.tech",
    "Realm": "acme",
    "ClientId": "acme-web",
    "ClientSecret": "YOUR_CLIENT_SECRET",
    "IdTokenSignedResponseAlg": "HS256",
    "AccessTokenSignedResponseAlg": "HS256"
  }
}

Next.js (NextAuth v4 e Auth.js v5)

O @hyper.authio/provider-nextauth 4.0.0 recebe os metadados de client do próprio NextAuth: client.id_token_signed_response_alg para o ID token e client.userinfo_signed_response_alg para o UserInfo assinado. O HS é verificado com o clientSecret (AUTH_AUTHIO_SECRET no v5). O provider não tem configuração para o access token: ele lê o access token só para as claims de session.authio, e quem o verifica é a sua API.

import NextAuth from 'next-auth'
import { createAuthio } from '@hyper.authio/provider-nextauth/v5'

export const authio = createAuthio({
  checks: ['pkce', 'state', 'nonce'],
  client: { id_token_signed_response_alg: 'HS256' },
  authorization: { params: { scope: 'openid profile email roles offline_access' } },
})

export const { handlers, auth, signIn, signOut } = NextAuth({
  providers: [authio.provider],
  callbacks: authio.callbacks,
  events: authio.events,
})

Problemas comuns