Download the PHP package ussoccerfederation/soccer-id-sdk-php without Composer

Soccer ID - U.S. Soccer Federation Partner Authentication SDK

Requirements

• PHP 8.2+
• Any PSR-18 compatible HTTP client, such as Guzzle
• Client ID & Secret from U.S. Soccer
• An agreed-upon callback URL hosted by your application (for OAuth2 code exchange)

About

Soccer ID is an initiative by the U.S. Soccer Federation to empower partner applications. This SDK simplifies the integration of third-party applications with U.S. Soccer's identity provider (IdP), enabling seamless user authentication via U.S. Soccer’s user pool.

With this SDK, developers can quickly implement secure login functionality, allowing users of their applications to authenticate using their U.S. Soccer credentials. It abstracts the complexities of identity federation, handling authentication flows, token validation, and user session management with minimal configuration. Whether you're building a membership portal, a fan engagement platform, or an internal team tool, this SDK streamlines the authentication process, ensuring a secure and consistent login experience.

Upgrading

Looking to upgrade from a previous version? See Upgrade Guide for help.

How it works

Your application will complete the expected Auth0 login flow, then will interact with U.S. Soccer's Identity Service to get or update information about the user. Afterward, you finalize the user's session, logging them into your app.

For a detailed view on all the pieces involved in this flow, see the sequence diagram below:

1. On your application's login page, provide the user with the option to "Login with U.S. Soccer."
2. Direct the user to U.S. Soccer's Universal Login page.
3. The user will then be prompted to enter their credentials (email and password) if they are not already logged into U.S. Soccer on the IdP end
4. The U.S. Soccer login portal will record some temporary data about the user's attempted login, and then...
5. Redirect the user to the configured "callback URL" for your application with some additional information used for verification in the next step.
6. Your application will need to perform a "code exchange" with the IdP. On success, the user can be considered authenticated
7. (Optional) Send a GET request to U.S. Soccer's Identity Service to get the user's profile. This contains additional information about the user. Use info from the login session + profile to upsert the user into your app's database.
8. You may provide updates/changes to the user's profile if needed.
9. Do any additional steps needed to log the user into your application and set their cookie(s).

Quick setup

Install the SDK:

Install a PSR-18 HTTP client if you don't already have one:

Configure your environment variables, or use .env. See .env.example for a good starting point.

If you are using Laravel, please jump forward to Laravel Integration

If you'd like to use .env files with your application and have not already included phpdotenv, do so now:

Next you will set up the object(s) needed to handle authentication. If you only need to log the user in and do not need to fetch/update user profiles, see Manually handling auth. Otherwise, continue below.

In your application, create an instance of the UssfAuth client. For example:

By default, the auth client will assume using PHP sessions for stateful data (data about the user if they are logged in) and encrypted cookies for transient data (temporary data needed only during the login process). To customize this, see Manually handling auth.

You will use the instance of UssfAuth on a few different pages: when the user chooses to log in via U.S. Soccer, during the callback phase of authentication, and when logging out. You may want to bind it to a singleton or use a factory to make it available to these pages.

Next, we need an action to associate with the user choosing to log in with U.S. Soccer. You may have a button or link that binds to /ussf_login.php, for example. We'll need to use our UssfAuth instance to initiate the login attempt:

That is enough to send the user over to Auth0 to prompt for permission and credentials. Next, we need a landing page that Auth0 will redirect them to in order to perform a code exchange. Let's call it /ussf_callback.php. It will also need access to the UssfAuth instance.

Finally, we need to allow the user to log out. Modify your logout script to perform a logout action against the UssfAuth instance if the user is logged in via this method. This may look something like:

With everything in place, you should now be able to start your app and complete the full login/logout cycle using U.S. Soccer Auth.

Manually handling auth

This section covers using the auth client directly rather than going through the UssfAuth class. With this, you will be able to handle log in, log out, and sessions however you would like.

Initiate login:

After providing credentials, the user will be redirected back to your configured callback endpoint. You will be expected to then handle the OAuth callback:

Example of working with user session:

Finally, you can log the user out. You have two options:

1. Log the user out by clearing their session locally. If the user tries to log back in soon, they will not be re-prompted for their credentials.
2. Log the user out by directing them to the IdP logout endpoint. This will log them out on the remote end as well, requiring them to re-enter their credentials upon logging in again.

Manually handling identities (Profiles)

Laravel Integration

Laravel allows you to access environment variables via the env() helper, however this is only considered valid while within the context of config files. Instead of accessing the environment variables directly when instantiating the UssfAuth instance, we'll need to create a config file. Create a new file: config/soccerid.php

Next, we'll create a service provider to bind our UssfAuth instance. Create a new file: Providers/SoccerIdServiceProvider.php

Remember to add the provider to boostrapping. For example, in Laravel 12, this is done by adding it to bootstrap/providers.php:

Finally, we need to hook up routing and serving. In the example below, we will do this the easy way. Add login, logout, and callback routes into /routes/web.php:

php // $userRepository->update(['name' => $session->user['name'], 'email' => $session->user['email']]); //

This is enough to test out functionality. Start your app and visit /login_ussf to give it a try. Once you're ready, move the core logic into a Controller and configure your final Routing.