CarpAuthService

Authenticates users at CAWS and holds the current session.

Configure it with a CarpAuthProperties using configure before signing in. authenticate opens the CAWS login page (OpenID Connect authorization code flow) and returns a CarpUser with an OAuthToken; other sign-in methods are available separately. The CAWS services (CarpBaseService) use the access token of CarpAuthService.currentUser to authorize their requests. The default constructor returns a shared instance, configured like this:

// The authentication configuration
late CarpAuthProperties authProperties = CarpAuthProperties(
  authURL: uri,
  clientId: 'studies-app',
  redirectURI: Uri.parse('carp-studies-auth://auth'),
  // For authentication at CAWS the path is '/auth/realms/Carp'
  discoveryURL: uri.replace(pathSegments: [
    'auth',
    'realms',
    'Carp',
  ]),
);

await CarpAuthService().configure(authProperties);

The CAWS login web page is opened when calling the authenticate method:

CarpUser user = await CarpAuthService().authenticate();

Constructors

CarpAuthService.instance

CarpAuthService.instance()

CarpAuthService

CarpAuthService()

Returns the singleton default instance of the CarpAuthService. Before this instance can be used, it must be configured using the configure method.

Properties

authEndpointUri

Uri get authEndpointUri

The URI for the authenticated endpoint for this CarpService.

authProperties

CarpAuthProperties get authProperties

The CARP authentication properties associated with the CARP Web Service. Accessing this before configure has been called fails a null assertion; check isConfigured first.

authStateChanges

Stream<AuthEvent> get authStateChanges

Notifies about changes to the user's authentication state (such as sign-in or sign-out) as defined in AuthEvent.

authenticated

bool get authenticated

Is a user authenticated? If true, the authenticated user is currentUser.

currentUser

CarpUser get currentUser

set currentUser (CarpUser? user)

Gets the current user. Accessing this when no user is authenticated fails a null assertion; check authenticated first.

isConfigured

bool get isConfigured

Has this service been configured?

manager

OidcUserManager? get manager

The OidcUserManager handling authentication.

Methods

authenticate

Future<CarpUser> authenticate()

Authenticate to this CARP service. This method will opens the authentication page of the Identity Server using a secure web view from the OS.

The discovery URL in the authProperties is used to find the Identity Server.

Returns the signed in user (with an OAuthToken access token), if successful. Throws a CarpServiceException if not successful.

authenticateWithMagicLink

Future<CarpUser> authenticateWithMagicLink(

1. String uri

)

Authenticate to this CARP service using an magic link URI generated by CAWS as part of an anonymous access flow.

The magic link can be found inside the .csv file downloaded from the portal.

authenticateWithUsernamePassword

Future<CarpUser> authenticateWithUsernamePassword({

1. required String username,
2. required String password,

})

Authenticate to this CARP service using a username and password.

The discovery URL in the authProperties is used to find the Identity Server.

Returns the signed in user (with an OAuthToken access token), if successful. Throws a CarpServiceException if not successful.

configure

Future<void> configure(

1. CarpAuthProperties authProperties

)

Configure the this instance of a Carp Service.

getCurrentUserProfile

CarpUser? getCurrentUserProfile(

1. OidcUser user

)

Gets the CARP profile of the current user from the JWT token of user. Returns null if the the user don't have an access token.

getCurrentUserProfileFromTokenResponse

CarpUser? getCurrentUserProfileFromTokenResponse(

1. TokenResponse tokenResponse

)

Gets the CARP profile of the current user from a TokenResponse. Using the parameters in the TokenResponse we create an OAuthToken to generate the CarpUser.

initManager

Future<void> initManager()

Initialize the OidcUserManager. This service must be configured before calling this method.

logout

Future<void> logout()

Log out from this CARP service

Opens a web view to clear cookies and end the session on the Identity Server.

Only use this method if you used authenticate to authenticate.

logoutNoContext

Future<void> logoutNoContext()

Log out of this CarpService, by clearing the current user.

Use this if you used authenticateWithUsernamePassword to authenticate, or when you want to log out without opening a web browser

magicLinkForCode

Future<String> magicLinkForCode(

1. String code

)

Resolve a short self-signup code (as shown to participants, e.g. XXGHW) to the magic link it belongs to, using the CAWS /api/self-signup/{code} endpoint. No authentication is needed.

The returned link can be passed to authenticateWithMagicLink. Throws a CarpNotFoundException if CAWS does not know the code.

nonNullAble

T nonNullAble<T>(

1. T? argument

)

Returns argument with a non-null assertion. A null argument fails that assertion (the CarpServiceException branches below cannot be reached).

refresh

Future<CarpUser> refresh()

Get a new access token for the current user based on the previously granted refresh token, using the Identity Server discovery URL.

This method is typically used when the access token has expired, and a new access token is needed to access the CARP web service. OAuthToken.expiresAt is the expiration time of the access token, not of the refresh token.

Returns the signed in user (with a new OAuthToken access token), if successful. Throws a CarpServiceException if not successful.