Árvore Docs Guia

NRPS — Names and Role Provisioning Services

NRPS é a API que o LMS expõe para que ferramentas externas (como a Árvore) consultem o roster de uma turma. A Árvore consome NRPS de duas formas: sob demanda, durante a launch, e via cron diário para manter o estado sincronizado.

Pré-requisitos

Para que NRPS funcione, a plataforma registrada na Árvore precisa ter:

  • auth_token_url preenchido (endpoint do LMS para client_credentials)
  • jwks_url preenchido (já necessário para launch)
  • O id_token do launch precisa trazer o claim https://purl.imsglobal.org/spec/lti-nrps/claim/namesroleservice

Sem o claim NRPS, a Árvore só conhece os usuários que efetivamente fazem launch — alunos que nunca clicaram no link nunca aparecem.

Autenticação

A Árvore se autentica no LMS via client credentials grant + signed JWT (RFC 7523):

POST /login/oauth2/token HTTP/1.1
Host: lms.exemplo.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
client_assertion=<JWT assinado com nossa chave privada>&
scope=https://purl.imsglobal.org/spec/lti-nrps/scope/contextmembership.readonly

O client_assertion é um JWT assinado com RS256 usando a chave privada cuja pública está em https://livros.arvore.com.br/api-arvore/lti/.well-known/jwks.json. Claims do JWT:

{
  "iss": "<client_id da Árvore na plataforma>",
  "sub": "<client_id da Árvore na plataforma>",
  "aud": "<auth_token_url da plataforma>",
  "iat": 1700000000,
  "exp": 1700000300,
  "jti": "<uuid>"
}

O LMS valida via JWKS da Árvore e devolve um access_token curto (tipicamente 1h).

Requisição de membership

Com o access_token:

GET /api/lti/courses/123/names_and_roles HTTP/1.1
Host: lms.exemplo.com
Authorization: Bearer <access_token>
Accept: application/vnd.ims.lti-nrps.v2.membershipcontainer+json

Resposta esperada:

{
  "id": "https://lms.exemplo.com/api/lti/courses/123/names_and_roles",
  "context": {
    "id": "course-12345",
    "label": "MATH-101",
    "title": "Matemática 6º ano A"
  },
  "members": [
    {
      "user_id": "user-7890",
      "name": "Maria da Silva",
      "email": "maria@escola.exemplo",
      "roles": ["http://purl.imsglobal.org/vocab/lis/v2/membership#Learner"],
      "status": "Active"
    }
  ]
}

Comportamento atual da Árvore

Hoje (MVP) o cron percorre todos os lti_resource_links ativos e:

  1. Solicita access_token para o LMS
  2. Faz GET <nrps_url>
  3. Para cada membro com status Active, verifica se já existe lti_user_links correspondente
  4. Atualiza lti_resource_links.last_sync_at

Provisionamento automático completo (criação de usuários novos a partir do roster sem esperar launch) está no roadmap. Para a maioria dos parceiros isso não é necessário porque o launch acontece naturalmente quando o aluno entra na atividade.

Erros comuns

  • 401 do LMS no access_token — geralmente significa que o client_id enviado no iss/sub do JWT não bate com o que o LMS reconhece. Verifique o client_id registrado na plataforma.
  • 400 com invalid_scope — o LMS não habilitou o escopo contextmembership.readonly para o tool. Pedir ao admin do LMS para habilitar.
  • 403 no NRPS GET — o access_token foi emitido para escopos diferentes. Confirme que o LMS aceita contextmembership.readonly.