OpenAthens LA support ended on 31 March 2020


Skip to end of metadata
Go to start of metadata

This page aggregates the troubleshooting pages from the runtime installation guide and the administration console installation guide.

Authentication errors

Flow error (authentication required)

This usually indicates that the runtime does not have a configured authentication store. This could be caused by:

  • No configured authentication store in the administration console
  • Runtime not yet connected to the administration console
  • No configuration has been published to the runtime

Flow error (Cannot locate entity)

OpenAthens LA is unaware of the service provider the user is trying to access. This could be caused by:

  • Metadata containing the entity has not been added in the admin console / not been published
  • The runtime cannot connect to the metadata address

Invalid configuration. No suitable flow for authentication query

Usually indicates a problem with the configuration of a delegated authentication provider such as Kerberos


When you visit /oala/sso, you should be redirected to /oala/login/<authstorename> and a 404 indicates a problem with the configuration of the authentication store.

There is no service provider to respond to

The page has been accessed directly without a request from a service provider

You must provide a valid session to perform this operation

Your datastore does not recognise the user identifier being used either in general, or for a specific user.

Error contacting your identity provider

Usually caused by the date and time being too far out of sync between the service provider and the runtime. Ensure you have enabled NTP on all runtimes.

Invalid assertion URL

Usually caused by the date and time being too far out of sync between the service provider and the runtime. Ensure you have enabled NTP on all runtimes.

No available assertion consumer service URL

There is no address to send a SAML response to specified in the SP's metadata. This is unlikely to happen with federation metadata but may happen if you are connecting to individual SPs outside of a federation such as your VLE.


Runtime server troubleshooting

Restart Apache to uncover errors

If your runtime is in service and otherwise working you may prefer to look only at logs however many problems can be diagnosed by restarting apache and looking at the error messages. If you restart Apache, users will not be able to log in during the restart, but will not otherwise be affected.

sudo service httpd restart

Apache errors referring to metadata or certificates

Error messages relating to metadata or certificates after an installation or update are usually cache related and clearing the cache is usually the solution. This can be done by going to the temporary files directory (/var/cache/openathens) and removing any files starting with ata-md and restarting apache. E.g:

sudo rm -f /var/cache/openathens/ata-md*
sudo service httpd restart

Apache error: Syntax error on line 16 of /etc/openathens/httpd/vhosts/001_proxy_links.conf: Invalid command 'OAProxyLoginLinkPath', perhaps misspelled or defined by a module not included in the server configuration.

This happens if you have changed the hostname associated with the proxy service. To rectify: reattach the runtime to the admin console by selecting it in the interface, clicking on edit and stepping through the wizard. Once done, publish from the admin console again.

Apache error: Couldn't open module: %{ATACAMA_HOME}/modules/ open shared object file: No such file or directory

This and similar mean that the Atacama home environment variable is unset. To fix, add a line to the following file:

sudo nano /etc/sysconfig/httpd

Add the line

export ATACAMA_HOME=/usr/share/atacama-platform

Apache error: Some of your private key files are encrypted for security reasons

This indicates that your web certificate has a password on it which means you need to manually restart Apache and enter it every time you publish from the admin console. To remove the password see: Removing a password from a certificate

If Apache does not start when the server is rebooted

Run the command:

sudo chkconfig httpd on

This will enable Apache during the startup processes

SE Linux

SE (or Security Enhanced) Linux can sometimes get in the way when you edit or update things. The check to see if it is the general cause is simple - temporarily disable it and see if the problem (usually with starting Apache) goes away. The commands are:

sudo setenforce Permissive
sudo setenforce Enforcing

If you can restart Apache with SE Linux in permissive mode, but not in enforcing mode, you will likely have some different security contexts set on certificate or cache files - see the section in: Certificates on the runtime

Other files that can sometimes be affected are:

sudo chcon system_u:object_r:httpd_modules_t:s0 /usr/lib/httpd/modules/
sudo chcon system_u:object_r:cert_t:s0/etc/pki/tls/certs/*.yourdomain.crt
sudo chcon system_u:object_r:cert_t:s0/etc/pki/tls/private/*.yourdoman.key 
sudo chcon system_u:object_r:cert_t:s0/usr/share/atacama-platform/keys/*.yourdomain.crt
sudo chcon system_u:object_r:var_t:s0/var/openathens/www/idp/oala/*

A read only filesystem is reported

This has only been observed on VMWare, and restarting the virtual server from the VMWare interface is usually the fix 

Adding an additional runtime replaces an existing runtime in the admin console interface

If you have cloned or copied an existing runtime, the admin console will see them as the same because they will have the same OpenAthens system guid. Deploying and configuring a new runtime from our template is the recommended approach.

After changing the proxy hostname, proxy resources cannot be accessed

Reattach the runtime(s), clear the cache on each runtime and restart Apache. Active users sessions will be lost.

Cannot update the runtime via Yum

As well as the username and password in the /etc/yum.repos.d/openathens.repo file, the access to the repository is also IP restricted using the same details as are on the account in the OpenAthens MD administration area. If the runtime is outside of the specified range, the connection will fail. Rectify by checking the credentials and adding the relevant IP address to the account.

Checking the logs

The runtime logs are in /var/log/openathens.

The platform-apache and login-apache files will be most useful. For more detail on the logs see: Where the logs are on the servers

Published changes do not appear to get applied 

Compare the published version number from the admin console with the model number reported by the runtime info page (on each runtime). The page is found at https://runtimeaddress/oala/info. 

If the numbers differ, this indicates the runtime is using a cached model. Clearing the cache and restarting apache is usually the remedy:

sudo rm -f /var/cache/openathens/*
sudo service httpd restart 

Statistics are not available in the administration console

No statistics are available

Usually a network problem - port 5051 is used for reading the logs and may have been blocked by a firewall setting.

Recent statistics are unavailable but older ones are

Restart the openathensd process:

 sudo service openathensd restart

Targeted ID values for a user change

The targetedID passed to service providers is generated from the user's username, your entityID, the resource's entityID and a salt value. Changes to any of these, including case, will change the targetedID. You should therefore be wary of selecting a username field that is not case normalised by your datastore.

Turn on debug level logging

Debug level logging can generate massive amounts of data on an active server so should be used with caution and turned off afterwards. See Where the logs are on the servers

Admin server troubleshooting

Admin console will not start (Windows)

The application is installed as a Windows service and should be set to startup automatically in services.msc.

The application is 32 bit and requires a 32 bit version of Java installed. The installer checks this, but removing 32bit Java later will break things.

Cannot see the proxy tab in the administration console after upgrading from v2.1

Because this function did not exist in older versions, it defaults to not visible. To rectify:

  1. Log into the administration console as the a user with access to modify accounts (e.g. admin) and select User management from the user menu (has your username on it)
  2. Select the user, clear any view and modify check boxes for the proxy and save
  3. Select the user again and add back the proxy view and modify access then save again.

The proxy tab should now be visible

Cannot update the administration console via Yum

As well as the username and password in the /etc/yum.repos.d/openathens.repo file, the access to the repository is also IP restricted using the same details as are on the account in the OpenAthens MD administration area. If the runtime is outside of the specified range, the connection will fail. Rectify by checking the credentials and adding the relevant IP address to the account.

Categories are not assigned as expected when based on multi-valued attributes such as memberOf

With multi-valued attributes, if any value matches the condition then the category applies. Where this can get tricky is the 'not' operators because they will apply the category if any value does not match, rather than only when all values do not match.

Changes on the runtime server couldn't be applied

Possible reasons include

  • There is a connection problem with the runtime - edit the connection and look for red crosses on page two of the wizard
  • There are no runtimes connected
  • If the progress bar waits on 95% for a long time, this indicates problems starting Apache

I've forgotten the superuser password

  1. Calculate an MD5 hash of a new password
  2. Locate the oala-login.xml file. Depending on your OS and architecture this will be in:

         Linux: /usr/share/openathensla-admin/data/oala-login.xml
    Windows 32: C:\Program Files\Eduserv\OpenAthens LA Admin\data\oala-login.xml
    Windows 64: C:\Program Files (x86)\Eduserv\OpenAthens LA Admin\data\oala-login.xml
  3. Open the file for editing and find the <login> section for the superuser account
  4. Update the password with the MD5 hash you crated earlier
  5. Restart the service

      Linux: sudo service openathensla-admin restart
    Windows: via services.msc

Runtime connection wizard has red crosses on the connection check

A couple will never be red, but four might be. If so, the problem will be:

  • Runtime software correctly installed. Should not be seen unless you are building your own runtime.
  • Runtime supports proxy. Will be red if you have not configured a proxy hostname on the configurations tab, or if you have uninstalled the proxy module on the runtime.
  • Runtime administration permission. Specified account not in the sudoers file. If this is the maint account on our VM image, restart the runtime.
  • Runtime statistics enabled. Usually a problem with the network blocking port 5051.

Statistics do not appear

If no statistics appear, check port 5051 is open between the runtime(s) and the administration console

If recent statistics, or specificic parts of the statistics such as the summary do not appear, restart openathensd on the runtime server

sudo service openathensd restart

Statistics for a user category have disappeared

They haven't been deleted and the transfers are still counted under the everyone category however the admin console will only display stats for categories that it knows exist. Rectify by adding the category back. You do not have to assign the category to any active users.

500 error message on publish

This is usually because the runtime hostname does not have a value

Where do I find my licence key?

It is displayed on Log in with the same account you used to download the software or configure yum.

Proxy server troubleshooting

Errors when accessing https URLs on proxy sites

This can happen if:

  • You do not have an appropriate wildcard SSL certificate installed (should be *
  • You have not enabled SSL/TLS settings on the proxy resource in question

Resource requires Form POST method

Form POST is not supported and workarounds such as find and replace are not secure. Sorry.

Users cannot see any proxy sites

If publishing does not update the page at, reattaching the runtime should eliminate any problems caused by changes to the proxy configuration. To reattach the runtime to the admin console: select the runtime on the overview tab, click on edit and step through the wizard. Once done, publish from the admin console again.

Users continually drop out of a proxied site

This can happen if:

  • not all hostnames of the resource are included in the proxy configuration
  • hostnames are included, but links have ports specified that are not included

In both cases, add the missing information to the proxy configuration

Users on really old browsers have problems accessing proxied sites

If you have a single runtime and use the same network interface for the proxy and IdP function, the system uses SNI (Server Name Indication) to keep things straight. Some older browsers did not support this (e.g. IE 6 and below).

Resolve by adding a second NIC to the runtime for the proxy to use. See: Activating the proxy server function

An ephemeral key size error prevents access to the administration console

Upgrade to the current version of the administration console or modify the key size - see: Ephemeral key size error on the latest browsers

  • No labels