TAO LTI 1.3 Symfony Bundle

https://github.com/oat-sa/bundle-lti1p3
Admin
An IMS certified Symfony bundle for LTI 1.3 implementations, designed to automate the usage of TAO...
Tokens:62,014
Snippets:399
Trust Score:10
License:LGPL-2.1
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Example: Accessing the User from Security

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/security-user.md

Shows how to retrieve the User object from Symfony's Security service and call its methods. The example uses the ProfileAction class and demonstrates getting the user identifier and roles, with a commented isGranted call.

```php
<?php

use Symfony\Bundle\SecurityBundle\Security;

final class ProfileAction
{
    public function __construct(private Security $security)
    {
    }

    public function __invoke(): Response
    {
        /** @var \OAT\Bundle\Lti1p3Bundle\Security\Authentication\User\User $user */
        $user = $this->security->getUser();

        $identifier = $user->getUserIdentifier();   // e.g. 'userIdentifier' or 'identifier' fallback
        $roles = $user->getRoles();                 // e.g. ['ROLE_USER'] or payload roles
        // $this->security->isGranted('ROLE_USER')

        return new Response('ok');
    }
}
```

--------------------------------

### Install bundle with Composer

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/README.md

Run this command to install the oat-sa/bundle-lti1p3 package. The associated flex recipe will generate configuration files and an environment variable for encryption key.

```console
$ composer require oat-sa/bundle-lti1p3
```

--------------------------------

### OidcInitiationAction basic example

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/controller-actions.md

Example of a basic OIDC initiation request. Sends a POST to /lti1p3/oidc/initiation with iss, login_hint, and target_link_uri parameters, expecting a 302 redirect to the platform authentication URL.

```php
<?php
// POST /lti1p3/oidc/initiation
// body: iss=http://platform.com&login_hint=user123&target_link_uri=http://tool.com/launch
// Response 302 Location: http://platform.com/lti1p3/oidc/authentication?scope=openid&...
```

--------------------------------

### Example — inspecting the compiled result

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/compiler-passes.md

Shows how to retrieve the compiled services after compilation. Comments indicate the expected service instances.

```php
<?php
// After compile, container has:
// $container->get(KeyChainRepositoryInterface::class)         -> KeyChainRepository built from config
// $container->get(RegistrationRepositoryInterface::class)     -> RegistrationRepository built from config
// $container->get(ScopeRepositoryInterface::class)            -> ScopeRepository with addScope() calls
```

--------------------------------

### JwksAction example request and response

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/controller-actions.md

Example of a GET request to the JWKS endpoint and the expected JSON response. The response contains a JWKS document with RSA keys.

```php
<?php
// Request: GET /lti1p3/.well-known/jwks/platformSet.json
// Response 200, Content-Type: application/json
// {"keys":[{"kty":"RSA","kid":"platformKey1","use":"sig","alg":"RS256",...}, ...]}
```

--------------------------------

### Example application config file (config/packages/lti1p3.yaml)

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/lti1p3-extension.md

Shows the expected configuration structure for the bundle, including scopes, key chains, platforms, tools, and registrations.

```yaml
# config/packages/lti1p3.yaml
lti1p3:
    scopes:
        - 'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem'
    key_chains:
        platformKey:
            key_set_name: 'platformSet'
            public_key: 'file://%kernel.project_dir%/config/secrets/dev/public.key'
            private_key: 'file://%kernel.project_dir%/config/secrets/dev/private.key'
    platforms:
        localPlatform:
            name: 'Local platform'
            audience: 'http://localhost/platform'
            oidc_authentication_url: 'http://localhost/lti1p3/oidc/authentication'
            oauth2_access_token_url: 'http://localhost/lti1p3/auth/platformKey/token'
    tools:
        localTool:
            name: 'Local tool'
            audience: 'http://localhost/tool'
            oidc_initiation_url: 'http://localhost/lti1p3/oidc/initiation'
    registrations:
        local:
            client_id: 'client_id'
            platform: 'localPlatform'
            tool: 'localTool'
            deployment_ids: ['deploymentId1']
            platform_key_chain: 'platformKey'
            tool_key_chain: 'toolKey'
```

--------------------------------

### Install NRPS library with Composer

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/doc/service/platform.md

Install the NRPS library via Composer to provide the membership service endpoint.

```console
$ composer require oat-sa/lib-lti1p3-nrps
```

--------------------------------

### KeyChainRepositoryBuilder usage example

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/repository-builders.md

Example of building a repository with a single key chain. The algorithm is optional and defaults to KeyInterface::ALG_RS256. The repository's find method returns a KeyChainInterface or null.

```php
<?php

use OAT\Bundle\Lti1p3Bundle\DependencyInjection\Builder\KeyChainRepositoryBuilder;

$repository = $builder->build([
    'key_chains' => [
        'platformKey' => [
            'key_set_name' => 'platformSet',
            'public_key' => 'file://config/secrets/dev/public.key',
            'private_key' => 'file://config/secrets/dev/private.key',
            'algorithm' => 'RS256',     // optional; defaults to KeyInterface::ALG_RS256
        ],
    ],
]);

$keyChain = $repository->find('platformKey');   // ?KeyChainInterface
```

--------------------------------

### curl request for OIDC initiation endpoint

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/endpoints.md

Initiates the OIDC login flow from the tool side. The endpoint accepts GET or POST with query/form parameters and redirects to the platform's authentication URL. This example uses query parameters.

```console
$ curl "http://localhost/lti1p3/oidc/initiation?iss=http://platform.com&login_hint=user123&target_link_uri=http://tool.com/launch"
```

--------------------------------

### Example — protecting a tool launch endpoint

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/message-authenticators.md

Configuration and code example for securing a tool launch endpoint using the lti1p3_message_tool firewall and accessing the LTI message security token.

```APIDOC
## Example — protecting a tool launch endpoint

### Description
Shows how to configure the security firewall to protect a tool launch endpoint and how to access the LTI message security token in a controller.

### Configuration Example
```yaml
# config/packages/security.yaml
security:
    firewalls:
        secured_tool_area:
            pattern: ^/launch
            stateless: true
            lti1p3_message_tool: true
```

### Code Example
```php
<?php

use OAT\Bundle\Lti1p3Bundle\Security\Authentication\Token\Message\LtiToolMessageSecurityToken;
use Symfony\Bundle\SecurityBundle\Security;

final class LtiLaunchAction
{
    public function __construct(private Security $security)
    {
    }

    public function __invoke(): Response
    {
        /** @var LtiToolMessageSecurityToken $token */
        $token = $this->security->getToken();

        $payload = $token->getPayload();
        $registration = $token->getRegistration();
        $state = $token->getState();   // OIDC state (MessagePayloadInterface)

        return new Response('launched');
    }
}
```
```

--------------------------------

### Enabling the bundle in bundles.php

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/lti1p3-bundle.md

Example of enabling the Lti1p3Bundle in the application's bundles.php file. Requires SecurityBundle to be enabled, otherwise a RuntimeException is thrown.

```php
<?php

return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
    // ...
    OAT\Bundle\Lti1p3Bundle\Lti1p3Bundle::class => ['all' => true],
];
```

--------------------------------

### Programmatic processing example

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/lti1p3-extension.md

Shows how to process configuration arrays using the Processor class. Missing optional keys default to null or 'RS256'.

```php
<?php

use OAT\Bundle\Lti1p3Bundle\DependencyInjection\Configuration;
use Symfony\Component\Config\Definition\Processor;

$configs = [
    ['key_chains' => ['k1' => ['key_set_name' => 'set', 'public_key' => 'file://pub.key']]],
];

$processed = (new Processor())->processConfiguration(new Configuration(), $configs);
// $processed['key_chains']['k1']['private_key'] === null
// $processed['key_chains']['k1']['algorithm'] === 'RS256'
```

--------------------------------

### Build from config array

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/repository-builders.md

Example of building a registration repository from a configuration array. The configuration includes key_chains, platforms, tools, and registrations. The registrations reference platform, tool, and key chains by id.

```php
<?php

use OAT\Bundle\Lti1p3Bundle\DependencyInjection\Builder\RegistrationRepositoryBuilder;

$repository = $builder->build([
    'key_chains' => [/* ... */],
    'platforms'  => [/* ... */],
    'tools'      => [/* ... */],
    'registrations' => [
        'local' => [
            'client_id' => 'client_id',
            'platform' => 'localPlatform',
            'tool' => 'localTool',
            'deployment_ids' => ['deploymentId1'],
            'platform_key_chain' => 'platformKey',
            'tool_key_chain' => 'toolKey',
        ],
    ],
]);
```

--------------------------------

### Define tool launch endpoint in routes.yaml

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/doc/message/tool.md

Example route configuration for a tool launch endpoint that will be protected by the lti1p3_message_tool firewall.

```yaml
#config/routes.yaml
platform_service:
    path: /launch
    controller: App\Action\Tool\LtiLaunchAction
```

--------------------------------

### Example — retrieving a registration in application code

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/registration-repository.md

Shows how to inject the RegistrationRepositoryInterface and use find, findByClientId, and findByPlatformIssuer. All methods return ?RegistrationInterface, so handle null in your logic.

```php
<?php

use OAT\Library\Lti1p3Core\Registration\RegistrationRepositoryInterface;

final class LaunchAction
{
    public function __construct(private RegistrationRepositoryInterface $repository)
    {
    }

    public function byId(): void
    {
        $registration = $this->repository->find('local');                 // config key 'local'
        $byClient = $this->repository->findByClientId('client_id');
        $byIssuer = $this->repository->findByPlatformIssuer('http://platform.com');

        // All return ?RegistrationInterface — handle null in your logic
        if (null === $registration) {
            // no registration with this identifier
        }
    }
}
```

--------------------------------

### Example — error case (PHP comments)

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/service-authenticator.md

PHP code comments showing example requests and responses for invalid or missing scopes.

```php
<?php
// GET /platform/service/ags/lineitem
// Authorization: Bearer <expired-or-invalid-token>
// Response 401 application/json
// {"error":{"message":"LTI service request authentication failed: Access token is invalid"}}

// Authorization: Bearer <valid token WITHOUT the firewall scope>
// Response 401 application/json
// {"error":{"message":"LTI service request authentication failed: Access token scopes are not supported"}}
```

--------------------------------

### Implement UserAuthenticatorInterface in PHP

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/doc/message/platform.md

Example PHP implementation of UserAuthenticatorInterface. The authenticate method receives the registration and login hint, and must return a UserAuthenticationResultInterface. The example returns a successful result with a UserIdentity.

```php
<?php

namespace App\Security\User;

use OAT\Library\Lti1p3Core\Registration\RegistrationInterface;
use OAT\Library\Lti1p3Core\Security\User\Result\UserAuthenticationResult;
use OAT\Library\Lti1p3Core\Security\User\Result\UserAuthenticationResultInterface;
use OAT\Library\Lti1p3Core\Security\User\UserAuthenticatorInterface;
use OAT\Library\Lti1p3Core\User\UserIdentity;

class UserAuthenticator implements UserAuthenticatorInterface
{
    public function authenticate(RegistrationInterface $registration, string $loginHint): UserAuthenticationResultInterface
    {
        // Perform user authentication based on the registration and login hint
        // (ex: owned session, LDAP, external auth service, etc)
        ...       

        return new UserAuthenticationResult(
           true,                                          // success
           new UserIdentity('userIdentifier', 'userName') // authenticated user identity
       ); 
    }
}
```

--------------------------------

### Example — error case

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/service-authenticator.md

Shows the response when authentication fails due to an invalid token or unsupported scopes.

```APIDOC
## Example — error case

### Description
Demonstrates the 401 error responses for invalid tokens and unsupported scopes.

### Request
- `GET /platform/service/ags/lineitem`
- `Authorization: Bearer <expired-or-invalid-token>`

### Response (401)
```json
{"error":{"message":"LTI service request authentication failed: Access token is invalid"}}
```

### Request
- `GET /platform/service/ags/lineitem`
- `Authorization: Bearer <valid token WITHOUT the firewall scope>`

### Response (401)
```json
{"error":{"message":"LTI service request authentication failed: Access token scopes are not supported"}}
```

```

--------------------------------

### Example — protecting a service endpoint

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/service-authenticator.md

Configuration and code example for protecting a service endpoint using the LTI 1.3 service authenticator with scopes.

```APIDOC
## Example — protecting a service endpoint

### Description
Shows how to configure a firewall and use the LTI service security token in a controller to protect a service endpoint.

### Configuration (security.yaml)
```yaml
security:
    firewalls:
        secured_service_ags_area:
            pattern: ^/platform/service/ags
            stateless: true
            lti1p3_service: { scopes: ['https://purl.imsglobal.org/spec/lti-ags/scope/lineitem'] }
```

### Controller Example
```php
<?php

use OAT\Bundle\Lti1p3Bundle\Security\Authentication\Token\Service\LtiServiceSecurityToken;
use Symfony\Bundle\SecurityBundle\Security;

final class LineItemAction
{
    public function __construct(private Security $security)
    {
    }

    public function __invoke(): Response
    {
        /** @var LtiServiceSecurityToken $token */
        $token = $this->security->getToken();

        $registration = $token->getRegistration();
        $accessToken = $token->getAccessToken();
        $scopes = $token->getScopes();

        return new Response(json_encode([...]));
    }
}
```

```

--------------------------------

### LtiServiceClientAction example

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/doc/service/tool.md

Example of a Symfony action that injects RegistrationRepositoryInterface and LtiServiceClientInterface, retrieves a registration, and makes an authenticated service request. The client caches the access token for a given TTL to avoid repeated token requests.

```php
<?php

declare(strict_types=1);

namespace App\Action\Tool\Service;

use OAT\Library\Lti1p3Core\Registration\RegistrationRepositoryInterface;
use OAT\Library\Lti1p3Core\Service\Client\LtiServiceClientInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class LtiServiceClientAction
{
    /** @var RegistrationRepositoryInterface */
    private $repository;

    /** @var LtiServiceClientInterface */
    private $client;
    
    public function __construct(RegistrationRepositoryInterface $repository, LtiServiceClientInterface $client)
    {
        $this->repository = $repository;
        $this->client = $client;
    }

    public function __invoke(Request $request): Response
    {
        $registration = $this->repository->find(...);
        
        $serviceResponse = $this->client->request(
            $registration,                    // Will ask the grant on the registration platform oauth2 endpoint, or form cache
            'GET',                            // Service call method
            'http://platform.com/service',    // Service call url
            ['some' => 'options'],            // Options
            ['scope1', 'scope2']              // Scopes
        );

        // Your logic based on the $serviceResponse ...
        
        return new Response(...);
    }
}
```

--------------------------------

### Build platform originating LTI launch with PlatformOriginatingLaunchBuilder

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/doc/message/platform.md

Use this PHP example to generate a platform originating LTI message for a tool. It injects the PlatformOriginatingLaunchBuilder and RegistrationRepositoryInterface, builds a resource link request message, and returns an HTML link response. Requires a registration repository with a 'local' registration and a valid tool launch URL.

```php
<?php

declare(strict_types=1);

namespace App\Action\Platform\Message;

use OAT\Library\Lti1p3Core\Message\Launch\Builder\PlatformOriginatingLaunchBuilder;
use OAT\Library\Lti1p3Core\Message\LtiMessageInterface;
use OAT\Library\Lti1p3Core\Registration\RegistrationRepositoryInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class MyPlatformAction
{
    /** @var PlatformOriginatingLaunchBuilder */
    private $builder;

    /** @var RegistrationRepositoryInterface */
    private $repository;

    public function __construct(PlatformOriginatingLaunchBuilder $builder, RegistrationRepositoryInterface $repository)
    {
        $this->builder = $builder;
        $this->repository = $repository;
    }

    public function __invoke(Request $request): Response
    {
        $message = $this->builder->buildPlatformOriginatingLaunch(
            $this->repository->find('local'),
            LtiMessageInterface::LTI_MESSAGE_TYPE_RESOURCE_LINK_REQUEST,
            'http://tool.com/launch',
            'loginHint'
        );

        return new Response($message->toHtmlLink('launch'));
    }
}
```

--------------------------------

### Example — error case

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/message-authenticators.md

Example of the error behavior when an id_token is replayed, showing the redirect response or exception thrown.

```APIDOC
## Example — error case

### Description
Shows the behavior when an id_token is replayed (nonce already used). If the id_token contains `launch_presentation.return_url`, a 302 redirect is sent with error parameters. Otherwise, the AuthenticationException is thrown and handled by Symfony's error handling (500).

### Example
```php
<?php
// POST /launch with id_token that has been replayed (nonce already used in cache)
// Response 302 Location: http://platform.com/return?lti_errormsg=Nonce%20already%20used&...
// (when the id_token contains launch_presentation.return_url)

// Or, without return_url: the AuthenticationException is thrown (500 via Symfony error handling)
```
```

--------------------------------

### Generate tool-originating LTI message with ToolOriginatingLaunchBuilder

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/doc/message/tool.md

Use this PHP example to build a tool-originating LTI message with the ToolOriginatingLaunchBuilder. It requires a RegistrationRepositoryInterface to find the 'local' registration and returns an HTML redirect form for the platform-side POST. The message type is LTI_MESSAGE_TYPE_RESOURCE_LINK_REQUEST and the target URL is 'http://platform.com/return'.

```php
<?php

declare(strict_types=1);

namespace App\Action\Tool\Message;

use OAT\Library\Lti1p3Core\Message\Launch\Builder\ToolOriginatingLaunchBuilder;
use OAT\Library\Lti1p3Core\Message\LtiMessageInterface;
use OAT\Library\Lti1p3Core\Registration\RegistrationRepositoryInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class MyToolAction
{
    /** @var ToolOriginatingLaunchBuilder */
    private $builder;

    /** @var RegistrationRepositoryInterface */
    private $repository;

    public function __construct(ToolOriginatingLaunchBuilder $builder, RegistrationRepositoryInterface $repository)
    {
        $this->builder = $builder;
        $this->repository = $repository;
    }

    public function __invoke(Request $request): Response
    {
        $message = $this->builder->buildToolOriginatingLaunch(
            $this->repository->find('local'),
            LtiMessageInterface::LTI_MESSAGE_TYPE_RESOURCE_LINK_REQUEST,
            'http://platform.com/return'
        );

        return new Response($message->toHtmlRedirectForm()); // has to be used this way due to the expected form POST platform side
    }
}
```

--------------------------------

### Example request and response for access token generation

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/controller-actions.md

Shows a POST request to /lti1p3/auth/platformKey/token with form-urlencoded body including grant_type, client_assertion_type, client_assertion, and scope. The response is a 200 with JSON containing access_token, token_type, expires_in, and scope.

```php
<?php
// POST /lti1p3/auth/platformKey/token
// 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=eyJ0eXAiOi...&scope=https://purl.imsglobal.org/spec/lti-ags/scope/lineitem

// Response 200, Content-Type: application/json;charset=UTF-8
// Cache-Control: no-store, Pragma: no-cache
// {"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1Ni...","token_type":"bearer","expires_in":3600,
//  "scope":"https://purl.imsglobal.org/spec/lti-ags/scope/lineitem"}
```

--------------------------------

### Configure lti1p3_message_tool firewall in security.yaml

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/security-factories.md

YAML configuration for the LtiToolMessageSecurityFactory firewall. The key is 'lti1p3_message_tool'. The example sets the pattern to '^/launch', enables stateless mode, and sets the factory to true, with an optional comment showing how to specify message types.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        secured_tool_area:
            pattern: ^/launch
            stateless: true
            lti1p3_message_tool: true            # or { types: ['LtiResourceLinkRequest'] }
```

--------------------------------

### Protecting a platform return endpoint - ReturnAction.php

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/message-authenticators.md

Example controller action that retrieves the LTI platform message security token and its payload and registration.

```php
<?php

use OAT\Bundle\Lti1p3Bundle\Security\Authentication\Token\Message\LtiPlatformMessageSecurityToken;
use Symfony\Bundle\SecurityBundle\Security;

final class ReturnAction
{
    public function __construct(private Security $security)
    {
    }

    public function __invoke(): Response
    {
        /** @var LtiPlatformMessageSecurityToken $token */
        $token = $this->security->getToken();

        $payload = $token->getPayload();
        $registration = $token->getRegistration();

        return new Response('ok');
    }
}
```

--------------------------------

### Verifying registration at compile time

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/lti1p3-bundle.md

Example of asserting that the bundle's build method registers the BuilderPass and ConfigurationPass compiler passes. Useful in kernel extensions or test bootstraps.

```php
<?php
// In a kernel extension or test bootstrap, assert the factories registered:

use OAT\Bundle\Lti1p3Bundle\Lti1p3Bundle;
use OAT\Bundle\Lti1p3Bundle\DependencyInjection\Compiler\BuilderPass;
use OAT\Bundle\Lti1p3Bundle\DependencyInjection\Compiler\ConfigurationPass;

$bundle = new Lti1p3Bundle();
$container = new ContainerBuilder();
// register 'security' extension + framework services, then:
$bundle->build($container);
// $container->getCompilerPassConfig()->getPasses() contains BuilderPass and ConfigurationPass
```

--------------------------------

### Example — protecting a service endpoint (PHP controller)

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/service-authenticator.md

PHP controller action that retrieves the LTI service security token and returns a JSON response.

```php
<?php

use OAT\Bundle\Lti1p3Bundle\Security\Authentication\Token\Service\LtiServiceSecurityToken;
use Symfony\Bundle\SecurityBundle\Security;

final class LineItemAction
{
    public function __construct(private Security $security)
    {
    }

    public function __invoke(): Response
    {
        /** @var LtiServiceSecurityToken $token */
        $token = $this->security->getToken();

        $registration = $token->getRegistration();
        $accessToken = $token->getAccessToken();
        $scopes = $token->getScopes();

        return new Response(json_encode([...]));
    }
}
```

--------------------------------

### Configure lti1p3_message_platform firewall in security.yaml

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/security-factories.md

YAML configuration for the LtiPlatformMessageSecurityFactory firewall. The key is 'lti1p3_message_platform'. The example sets the pattern to '^/platform/return', enables stateless mode, and sets the factory to true, with an optional comment showing how to specify message types.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        secured_platform_area:
            pattern: ^/platform/return
            stateless: true
            lti1p3_message_platform: true        # or { types: ['LtiDeepLinkingResponse'] }
```

--------------------------------

### Example — default behavior

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/exception-handler.md

Shows the default behavior when authentication fails: the handler redirects to the return URL with error parameters. The comment describes the expected 302 response.

```php
<?php
// Tool firewall: lti1p3_message_tool on ^/launch
// POST /launch with id_token=<token whose launch_presentation.return_url = http://platform.com/return?foo=1>

// Authentication fails (e.g. invalid signature):
// Response 302 Location: http://platform.com/return?foo=1&lti_errormsg=LTI%20tool%20message%20request%20authentication%20failed%3A%20...
//   &lti_errorlog=<same>&lti_msg=<same>&lti_log=<same>
```

--------------------------------

### OidcAuthenticationAction basic example

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/controller-actions.md

Illustrates a successful OIDC authentication request. The response is a 200 HTML auto-submit form that posts the id_token and state to the tool's launch URL.

```php
<?php
// GET /lti1p3/oidc/authentication?scope=openid&response_type=id_token&...
// Response 200 text/html:
// <html><body onload="document.getElementById('ltiLaunchForm').submit();">
//   <form id="ltiLaunchForm" method="POST" action="http://tool.com/launch">
//     <input type="hidden" name="id_token" value="eyJ0eXAiOi..."/><input ... name="state" .../>
```

--------------------------------

### Configure tool OIDC initiation URL in lti1p3.yaml

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/doc/message/tool.md

Set the oidc_initiation_url for your tool to the default route [GET,POST] /lti1p3/oidc/initiation. The bundle generates a state JWT and nonce that must be returned unaltered by the platform after OIDC authentication.

```yaml
# config/packages/lti1p3.yaml
lti1p3:
    tools:
        myTool:
            name: "My Tool"
            audience: "http://tool.com"
            oidc_initiation_url: "http://tool.com/lti1p3/oidc/initiation"
            launch_url: "http://tool.com/launch"
            deep_linking_url: ~
```

--------------------------------

### Example error responses for invalid scope and invalid client

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/controller-actions.md

Shows error responses: a 400 with invalid_scope error and a 401 with invalid_client error, both in JSON format.

```php
<?php
// Response 400 application/json
// {"error":"invalid_scope","error_description":"The requested scope is invalid, unknown, or malformed", ...}

// Response 401 application/json
// {"error":"invalid_client","error_description":"Client authentication failed", ...}
```

--------------------------------

### Example — custom handler (translation) service configuration

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/exception-handler.md

Configures the custom exception handler class in services.yaml to override the default handler.

```yaml
<?php
// config/services.yaml
services:
    OAT\Bundle\Lti1p3Bundle\Security\Exception\LtiToolMessageExceptionHandlerInterface:
        class: App\Security\Exception\MyExceptionHandler
```

--------------------------------

### Configure LTI 1.3 firewalls in security.yaml

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/configuration.md

Example YAML configuration for securing tool, service, and platform areas using the lti1p3_message_tool, lti1p3_service, and lti1p3_message_platform firewall keys. The 'types' option restricts allowed LTI message types, and 'scopes' restricts OAuth2 scopes.

```yaml
security:
    firewalls:
        secured_tool_area:
            pattern: ^/launch
            stateless: true
            lti1p3_message_tool: { types: ['LtiResourceLinkRequest'] }
        secured_service_ags_area:
            pattern: ^/platform/service/ags
            stateless: true
            lti1p3_service: { scopes: ['https://purl.imsglobal.org/spec/lti-ags/scope/lineitem'] }
        secured_platform_area:
            pattern: ^/platform/return
            stateless: true
            lti1p3_message_platform: true
```

--------------------------------

### Example — custom handler (translation) implementation

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/exception-handler.md

A custom handler that translates the exception message and redirects to a fixed error URL with the translated message.

```php
<?php
declare(strict_types=1);

namespace App\Security\Exception;

use OAT\Bundle\Lti1p3Bundle\Security\Exception\LtiToolMessageExceptionHandlerInterface;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Throwable;

class MyExceptionHandler implements LtiToolMessageExceptionHandlerInterface
{
    public function handle(Throwable $exception, Request $request): Response
    {
        $message = urlencode('translated: ' . $exception->getMessage());

        return new RedirectResponse(sprintf('http://platform.com/error?lti_errormsg=%s', $message));
    }
}
```

--------------------------------

### Catching a misconfiguration

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/repository-builders.md

Example of catching an InvalidArgumentException when building the repository. The exception message includes the undefined platform, tool, or key chain and possible values. The error is logged and the configuration should be fixed.

```php
<?php

use InvalidArgumentException;

try {
    $repository = $builder->build($configuration);
} catch (InvalidArgumentException $exception) {
    // e.g. "Tool unknownTool is not defined, possible values: localTool"
    error_log($exception->getMessage());
    // Fix configuration; surface the error during application startup
}
```

--------------------------------

### Configure platform OIDC authentication URL in lti1p3.yaml

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/doc/message/platform.md

YAML configuration for the platform's OIDC authentication URL. The default route is [GET,POST] /lti1p3/oidc/authentication.

```yaml
# config/packages/lti1p3.yaml
lti1p3:
    platforms:
        myPlatform:
            name: "My Platform"
            audience: "http://platform.com"
            oidc_authentication_url: "http://platform.com/lti1p3/oidc/authentication"
            oauth2_access_token_url: "http://platform.com/lti1p3/auth/platformKey/token"
```

--------------------------------

### Firewall configuration for lti1p3_service

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/security-factories.md

YAML configuration for the `lti1p3_service` firewall, used to protect a service area with the specified scopes. The example secures the `/platform/service/ags` pattern with the `https://purl.imsglobal.org/spec/lti-ags/scope/lineitem` scope.

```yaml
# config/packages/security.yaml
security:
    firewalls:
        secured_service_ags_area:
            pattern: ^/platform/service/ags
            stateless: true
            lti1p3_service: { scopes: ['https://purl.imsglobal.org/spec/lti-ags/scope/lineitem'] }
```

--------------------------------

### GET, POST /lti1p3/oidc/initiation

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/endpoints.md

Initiates the OIDC login flow for the tool side. Accepts standard IMS login initiation parameters and redirects the user to the platform's OIDC authentication URL.

```APIDOC
## GET, POST /lti1p3/oidc/initiation

### Description
Initiates the OIDC login flow for the tool side. Accepts standard IMS login initiation parameters and redirects the user to the platform's OIDC authentication URL.

### Method
GET, POST

### Endpoint
/lti1p3/oidc/initiation

### Parameters
#### Query Parameters
- **iss** (string) - Required - Platform issuer (must match a configured platform audience)
- **login_hint** (string) - Required - User/login hint forwarded back by the platform
- **target_link_uri** (string) - Required - Final launch URL
- **lti_message_hint** (string) - Optional - Opaque hint (forwarded)
- **client_id** (string) - Optional - Platform client id (forwarded)
- **any other login-initiation param** (string) - Optional - Forwarded through the initiator

#### Request Body
Form body parameters are also accepted (same fields as query parameters).

### Response
#### Success Response (302)
- **Location** (string) - Redirect URL to the platform's OIDC authentication endpoint with query parameters: `scope`, `response_type`, `client_id`, `redirect_uri`, `state`, `nonce`, `prompt`, `login_hint`.

#### Error Response (400)
- **Body** (text/html) - HTML-escaped error message (e.g. registration/initiation failure).

### Request Example
```console
$ curl "http://localhost/lti1p3/oidc/initiation?iss=http://platform.com&login_hint=user123&target_link_uri=http://tool.com/launch"
```
```

--------------------------------

### curl request to OIDC authentication endpoint

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/endpoints.md

Example curl command to initiate OIDC authentication. The request includes required query parameters: scope, response_type, client_id, redirect_uri, state, nonce, login_hint, and prompt. The endpoint returns an HTML form that auto-submits to the tool launch URL.

```console
$ curl "http://localhost/lti1p3/oidc/authentication?scope=openid&response_type=id_token&client_id=client_id&redirect_uri=http://tool.com/launch&state=...&nonce=...&login_hint=user123&prompt=none"
```

--------------------------------

### GET, POST /lti1p3/oidc/initiation

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/endpoints.md

Initiates the OpenID Connect (OIDC) login flow for LTI 1.3. This endpoint is called by the platform to start the authentication process.

```APIDOC
## GET, POST /lti1p3/oidc/initiation

### Description
Initiates the OpenID Connect (OIDC) login flow for LTI 1.3. This endpoint is called by the platform to start the authentication process.

### Method
GET, POST

### Endpoint
/lti1p3/oidc/initiation

### Parameters
#### Query Parameters
- **iss** (string) - Required - The issuer identifier of the platform.
- **login_hint** (string) - Required - The login hint provided by the platform.
- **target_link_uri** (string) - Required - The target link URI.
- **client_id** (string) - Required - The client ID.
- **lti_message_hint** (string) - Optional - The LTI message hint.

### Response
#### Success Response (302)
Redirects to the authentication endpoint with the OIDC parameters.
```

--------------------------------

### Configure lti1p3.yaml with key chains, platforms, tools, and registrations

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/doc/quickstart/configuration.md

The flex recipe creates config/packages/lti1p3.yaml with this default configuration. It defines two key chains (platformKey and toolKey), one platform (localPlatform), one tool (localTool), and one registration (local) that deploys the tool for the platform. Hostnames in the URLs must be adapted to your environment.

```yaml
# config/packages/lti1p3.yaml
lti1p3:
    key_chains:
        platformKey:
            key_set_name: "platformSet"
            public_key: "file://%kernel.project_dir%/config/secrets/dev/public.key"
            private_key: "file://%kernel.project_dir%/config/secrets/dev/private.key"
            private_key_passphrase: ~
        toolKey:
            key_set_name: "toolSet"
            public_key: "file://%kernel.project_dir%/config/secrets/dev/public.key"
            private_key: "file://%kernel.project_dir%/config/secrets/dev/private.key"
            private_key_passphrase: ~
    platforms:
        localPlatform:
            name: "Local platform"
            audience: "http://localhost/platform"
            oidc_authentication_url: "http://localhost/lti1p3/oidc/authentication"
            oauth2_access_token_url: "http://localhost/lti1p3/auth/platformKey/token"
    tools:
        localTool:
            name: "Local tool"
            audience: "http://localhost/tool"
            oidc_initiation_url: "http://localhost/lti1p3/oidc/initiation"
            launch_url: ~
            deep_linking_url: ~
    registrations:
        local:
            client_id: "client_id"
            platform: "localPlatform"
            tool: "localTool"
            deployment_ids:
                - "deploymentId1"
            platform_key_chain: "platformKey"
            tool_key_chain: "toolKey"
            platform_jwks_url: ~
            tool_jwks_url: ~

```

--------------------------------

### OidcInitiationAction error case example

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/controller-actions.md

Example of an error case when an invalid iss is provided. The response is a 400 with an HTML-escaped error message body.

```php
<?php
// POST /lti1p3/oidc/initiation with iss=http://unknown.com
// Response 400
// Body: "Registration not found for platform issuer http://unknown.com" (HTML-escaped)
```

--------------------------------

### Generate a key pair using OpenSSL

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/doc/quickstart/configuration.md

Commands to create a directory and generate a private and public key pair using OpenSSL.

```console
$ mkdir -p config/secrets/dev
$ openssl genrsa -out config/secrets/dev/private.key 2048
$ openssl rsa -in config/secrets/dev/private.key -outform PEM -pubout -out config/secrets/dev/public.key
```

--------------------------------

### Run tests with PHPUnit

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/README.md

Execute this command to run the bundle's test suite. Available test suites are defined in phpunit.xml.dist.

```console
$ vendor/bin/phpunit
```

--------------------------------

### OidcAuthenticationAction error example

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/controller-actions.md

Shows the response when authentication fails, such as an unauthenticated login hint. Returns a 401 status with escaped error text.

```php
<?php
// Response 401
// Body: "Unable to authenticate user for login hint user123"
```

--------------------------------

### Configuration class skeleton

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/lti1p3-extension.md

Shows the public methods of the Configuration class that build the configuration tree.

```php
class Configuration implements ConfigurationInterface
{
    public function getConfigTreeBuilder(): TreeBuilder

    public function addScopesConfiguration(ArrayNodeDefinition $rootNode): self

    public function addKeyChainsConfiguration(ArrayNodeDefinition $rootNode): self

    public function addPlatformsConfiguration(ArrayNodeDefinition $rootNode): self

    public function addToolsConfiguration(ArrayNodeDefinition $rootNode): self

    public function addRegistrationsConfiguration(ArrayNodeDefinition $rootNode): self
}
```

--------------------------------

### Access LtiPlatformMessageSecurityToken in controller (PHP)

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/doc/message/platform.md

Example controller action that retrieves the LtiPlatformMessageSecurityToken from the security token storage to access the registration, payload, and validation results.

```php
<?php

declare(strict_types=1);

namespace App\Action\Platform;

use OAT\Bundle\Lti1p3Bundle\Security\Authentication\Token\Message\LtiPlatformMessageSecurityToken;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Bundle\SecurityBundle\Security;

class ReturnAction
{
    /** @var Security */
    private $security;

    public function __construct(Security $security)
    {
        $this->security = $security;
    }

    public function __invoke(Request $request): Response
    {
        /** @var LtiPlatformMessageSecurityToken $token */
        $token = $this->security->getToken();

        // Related registration
        $registration = $token->getRegistration();

        // Related LTI message payload
        $payload = $token->getPayload();

        // You can even access validation results
        $validationResults = $token->getValidationResult();

        // Your service endpoint logic ...

        return new Response(...);
    }
}
```

--------------------------------

### Access LtiToolMessageSecurityToken in controller

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/doc/message/tool.md

Example controller action that retrieves the LtiToolMessageSecurityToken from the security token storage to access registration, payload, state, and validation results.

```php
<?php

declare(strict_types=1);

namespace App\Action\Tool;

use OAT\Bundle\Lti1p3Bundle\Security\Authentication\Token\Message\LtiToolMessageSecurityToken;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Bundle\SecurityBundle\Security;

class LtiLaunchAction
{
    /** @var Security */
    private $security;

    public function __construct(Security $security)
    {
        $this->security = $security;
    }

    public function __invoke(Request $request): Response
    {
        /** @var LtiToolMessageSecurityToken $token */
        $token = $this->security->getToken();

        // Related registration
        $registration = $token->getRegistration();

        // Related LTI message payload
        $payload = $token->getPayload();

        // Related OIDC state
        $state = $token->getState();

        // You can even access validation results
        $validationResults = $token->getValidationResult();

        // Your service endpoint logic ...

        return new Response(...);
    }
}
```

--------------------------------

### Complete LTI 1.3 Bundle Configuration (config/packages/lti1p3.yaml)

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/configuration.md

YAML configuration for the LTI 1.3 bundle. Defines scopes, key chains (platformKey, toolKey), platforms, tools, and registrations. Key chains reference public/private keys and specify the signing algorithm. Registrations link a client_id to a platform and tool, and specify deployment IDs and JWKS URLs.

```yaml
lti1p3:
    scopes:
        - 'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem'
    key_chains:
        platformKey:
            key_set_name: 'platformSet'
            public_key: 'file://%kernel.project_dir%/config/secrets/dev/public.key'
            private_key: 'file://%kernel.project_dir%/config/secrets/dev/private.key'
            private_key_passphrase: ~
            algorithm: 'RS256'
        toolKey:
            key_set_name: 'toolSet'
            public_key: 'file://%kernel.project_dir%/config/secrets/dev/public.key'
            private_key: 'file://%kernel.project_dir%/config/secrets/dev/private.key'
    platforms:
        myPlatform:
            name: 'My Platform'
            audience: 'http://platform.com'
            oidc_authentication_url: 'http://platform.com/lti1p3/oidc/authentication'
            oauth2_access_token_url: 'http://platform.com/lti1p3/auth/platformKey/token'
    tools:
        myTool:
            name: 'My Tool'
            audience: 'http://tool.com'
            oidc_initiation_url: 'http://tool.com/lti1p3/oidc/initiation'
            launch_url: 'http://tool.com/launch'
            deep_linking_url: ~
    registrations:
        myRegistration:
            client_id: 'myClientId'
            platform: 'myPlatform'
            tool: 'myTool'
            deployment_ids: ['deploymentId1', 'deploymentId2']
            platform_key_chain: 'myPlatformKey'
            tool_key_chain: 'myToolKey'
            platform_jwks_url: 'http://platform.com/lti1p3/.well-known/jwks/platformSet.json'
            tool_jwks_url: 'http://tool.com/lti1p3/.well-known/jwks/toolSet.json'
            order: 1

```

--------------------------------

### GET, POST /lti1p3/oidc/authentication

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/endpoints.md

Handles the OIDC authentication request and returns an authentication response. This endpoint is part of the LTI 1.3 message launch flow.

```APIDOC
## GET, POST /lti1p3/oidc/authentication

### Description
Handles the OIDC authentication request and returns an authentication response. This endpoint is part of the LTI 1.3 message launch flow.

### Method
GET, POST

### Endpoint
/lti1p3/oidc/authentication

### Parameters
#### Query Parameters
- **iss** (string) - Required - The issuer identifier of the platform.
- **login_hint** (string) - Required - The login hint provided by the platform.
- **target_link_uri** (string) - Required - The target link URI.
- **client_id** (string) - Required - The client ID.
- **lti_message_hint** (string) - Optional - The LTI message hint.

### Response
#### Success Response (200)
Returns the authentication response, typically an HTML page or a redirect.
```

--------------------------------

### Using LtiServiceSecurityToken to access token data

Source: https://github.com/oat-sa/bundle-lti1p3/blob/master/_autodocs/api-reference/security-tokens.md

Example usage of LtiServiceSecurityToken to retrieve registration, access token, and scopes, and to check authorization using scopes as roles.

```php
<?php
/** @var LtiServiceSecurityToken $token */
$token = $this->security->getToken();

$registration = $token->getRegistration();      // ?RegistrationInterface
$accessToken  = $token->getAccessToken();       // ?TokenInterface
$scopes       = $token->getScopes();            // ['https://purl.imsglobal.org/spec/lti-ags/scope/lineitem']
$isGranted    = $this->security->isGranted('https://purl.imsglobal.org/spec/lti-ags/scope/lineitem'); // scopes are roles
```
Tokens:
Raw