Tech Blog

Working with AEK and campusM token-based authentication

A bit longer than the usual post, this will describe how to work with your local AEK development environment and invoke token-based campusM authentication in your AEK projects. If you are not sure if your campusM environment and profiles are setup with token-based authentication, please ask your campusM support or project team contact.

  1. https://npm.campusm.net/-/docs/@ombiel/aek-server-side/

 

Impact on aek-devserver

The devserver isn’t a valid target for the authentication process; you’ll find that if you try to log in, if successful, you’ll be forwarded to the actual web app, instead of localhost. To get around this, we need to copy the cookies over (from an active web app session) using a browser plugin; our recommendation for Chrome is EditThisCookie. Once installed, this is accessed from your extensions toolbar on the top-right of your Chrome window.

Here are the steps you need to follow each time you want to run against a web app that requires a relevant token-based (CMAuth) profile login:

  1. Log in to the web app itself, for example https://uni.campusm.exlibrisgroup.com.
  2. Open EditThisCookie on this page and select Export (fifth icon from the left). This copies the cookies for that page to your clipboard; it doesn’t export them to a file.
  3. Paste them into a text editor.
  4. Find and replace all instances of the hostname of the app (e.g. in the above case, this would be https://uni.campusm.exlibrisgroup.com) with localhost.
  5. Start up your local devserver instance. Wait for the profile selection page to appear before doing anything else.
    1. If the app you’re running your devserver against only has one profile (and it’s a token-based CMAuth profile), you will be automatically redirected.
    2. You’ll need to stop the page loading before you’re redirected.
  6. Open EditThisCookie on your localhost:5000 page and select Import (third icon from the left if no cookies exist yet, fourth icon from the left otherwise).
  7. Paste the edited cookies into the text box, and click the green tick at the bottom.
  8. Select the relevant token-based CMAuth profile (the same one you logged into on the actual web app).
    1. If you stopped the page loading due to it only having a single profile, just refresh the page.

It should log you into the correct profile, where you can then access your development tile as normal.

Note: these instructions also apply for legacy SSO profiles as well.

 

Token-based CMAuth in Twig / ECT

The main way we know if an CMAuth session has been established is whether or not the Twig function to fetch the token-based user attributes works or not:

{% set utils = aek.extension("CMAuthUtilities") %}
{% set attrs = utils.getTokenAttributes() %}

{% if attrs|get_item("firstName") %}

  {# ... #}

{% endif %}

You don’t need to explicitly check for attributes on the ECT side; you might find it’s easier to pass them all back to the JSX layer and put validation in at that end. It may be that you’re looking for a particular custom user attribute (like a library ID that isn’t required for the basic CMAuth flow); these are often found under “extraAttrs” and are set up by your TPM for you.

 

Other CMAuth Utilities

CMAuthUtilities gives us access to various other functions depending on the configuration of your CMAuth integration. You can see them in Twig code, below:

{% set oAuthToken = utils.getOAuthAccessToken() %}
{% set extraAttributes = utils.getExtraAttributes() %}
{% set encryptedExtraAttributes = utils.getEncryptedExtraAttributes() %}

getOAuthToken – returns the user’s personal oAuth token for passing onto other services authenticated with the same provider.

getExtraAttributes – returns the extra attributes mapped, if any. Commonly used to map user IDs for third-party integrations.

getEncryptedExtraAttributes – returns encrypted extra attributes mapped, if any.

If any of these are null and you’re expecting them not to be, please check with your campusM support team or project contact – enabling these may require additional initial setup steps.

 

Common Issues

AEK window showing “unable to retrieve preview screen from server” / “preview not available”

The only time you should encounter this is if you started your runserver without the correct username prefix. For example, for APAC (AP01), you should be logging in as ap::username, instead of just username (for EU01). The common ones you’ll need to use are:

  • na:: (NA01)
  • ap:: (AP01)

Web service call returning “unable to find username in token”

This normally means you’re mixing authentication types between the AEK code. CMAuth works solely via the token, so a web service call expecting a username and / or password (such as a typical Web Service Endpoint in App Manager pointing at an old “Username/Password” authentication type typical for legacy LDAP profiles) won’t find this in a CMAuth session, and will return that error.

If you continue to be redirected to the web app

  1. Make sure the session you copied the cookies from is a fresh session, and not one from a previous browser session. It could be that the login has actually expired.
  2. Make sure you copied the cookies from the same hostname that your AEK package is targeting.

App is auto-selecting the profile, and redirecting me to the IDP automatically

There are a couple of possible reasons for this.

Firstly, that your app only has one profile set up, and it’s a token-based CMAuth profile. There isn’t an easy way around this; you have to stop the browser activity (usually to the left of your address bar) before the automatic redirect kicks in, and then import the session cookies outlined under “Impact on aek-devserver”.

Secondly, that there are cookies set against localhost that contain data relevant to other hostnames that aren’t the one you’re trying to run against currently. Delete all cookies for localhost and refresh the page. This should take you to profile selection again, at which point you can import the session cookies as detailed above.

 


Glossary

AEK. Application Extension Kit.

CMAuth. “campusM” token-based authentication (supports SAML 2, OAuth 2 and LDAP). Not to be confused with username/password based legacy LDAP, legacy SAML SSO or legacy OAuth)

OAuth. Open Authorization. campusM supports OAuth 2

Twig. A PHP templating engine. See the Server Docs (linked at the start) for more information.

ECT. Intermediary file format within AEK 2.0, see the Server Docs for more information.

 

Leave a Reply