Web scripts in alfresco allows you to easily integrate your custom front-end application with alfresco repository. One of the key thing to understand for such integration using REST API is, how do you establish the user authentication and execute each web script request to the repository in the respective user context. If you have been working on Alfresco for quite a long time then you must be knowing that with the help of alf_ticket, it is easily achievable. If you are new to Alfresco and have just the preliminary information about web scripts then you may be wondering what is this alf_ticket and how it is useful while invoking the web scripts in Alfresco. Let's take a look at some of the key facts you must know about it.
How to obtain alf_ticket?
There is an out-of-the-box login web script available in Alfresco wherein you can provide username and password and in return this web script will return you the ticket information for user's established authenctiated session against the alfresco repository. Following are the details about the login web script.
By default the webscript returns the XML response, however, you can get the JSON response as well. Just modify the web script URL above with login.json instead of login to get the JSON response back.
For login web script, both GET and POST methods are supported. Ideally, it is preferable to invoke login web script with POST method.
How to use the alf_ticket?
Once you have obtained the alf_ticket for a user then while invoking any further web scripts (which have authentication attribute setup as user in the web script description document), you need to pass the alf_ticket information in order to let the Alfresco repository know that it needs to execute the requested web script code in the context of a user whose authentication ticket information has been passed using alf_ticket.
Following is one example about how you pass alf_ticket to execute the get content web script run in the context for the admin user's authentication session for which we just obtained alf_ticket above.
http://localhost:8080/alfresco/service/api/node/content/workspace/SpacesStore/18d2fa04-70ba-4865-afe6-e097b75f0576?alf_ticket=TICKET_1f80f5e7bcdad060f7c0de95889541f704979f10
If web script itself is expecting some other querystring parameters then you can append alf_ticket at the end using &alf_ticket.
Does the alf_ticket expire?
By default, it is pre-configured in Alfresco that authentication tickets do get expired. The following configuratoin property takes care of setting up whether authentication tickets will expire or not. You can set this property to false in alfresco-global.properties file, if you do not want the alf_ticket to get expired. However, you may not want to do that in regular scenarios.
authentication.ticket.ticketsExpire=true
What is the expiry mode for alf_ticket?
If ticket expiry mode is set as true as mentioned in above configuration property then you can also configure when should alf_ticket get expired. The following configuration property takes care of it.
authentication.ticket.expiryMode=AFTER_INACTIVITY
By default, it is set to AFTER_INACTIVITY (we will see in next section how does it is determined that user is inactive). You can configure this property's value in alfresco-global.preoprties file.
The other two possible values for this configuration property are AFTER_FIXED_TIME and DO_NOT_EXPIRE.
When authentication.ticket.ticketsExpire is set to true, you should either set this property to AFTER_INACTIVITY or AFTER_FIXED_TIME. When authentication.ticket.ticketsExpire is set to false then use DO_NOT_EXPIRE as the value.
When does alf_ticket expire?
When authentication.ticket.ticketsExpire is set as true and authentication.ticket.expiryMode is set as AFTER_INACTIVITY or AFTER_FIXED_TIME then you can configure what is the valid duration for alf_ticket validity using the following property authentication.ticket.validDuration in alfresco-global.properties file.
By default, it is configured to be valid for PT1H i.e. valid for one hour.
The way it works is, if expiryMode is set as AFTER_INACTIVITY then if user does not do any activity during one hour then ticket automatically gets expired.
If expiryMode is set as AFTER_FIXED_TIME then if user do or don't do any activity then still the ticket gets expired after one hour.
How to invalidate alf_ticket explicitly?
For example, when user logs out you may want to invalidate the user ticket at the same time as soon as user is logged out. In order to do so, you can use out-of-the-box Alfresco web script.
Web script URL http://localhost:8080/alfresco/service/api/login/ticket/TICKET_1f80f5e7bcdad060f7c0de95889541f704979f10?alf_ticket=TICKET_1f80f5e7bcdad060f7c0de95889541f704979f10.
It uses the HTTP method DELETE. Also, note that we also have explicitly provided alf_ticket querystring parameter as well.
How to validate if alf_ticket is still valid or not?
If at any point of time, you want to find out if alf_ticket for the user is still valid or not, you can use the following out-of-the-box Alfresco web script. It is basically the same web script url we used in above section however, it is invoked using HTTP GET method instead of DELETE.
http://localhost:8080/alfresco/service/api/login/ticket/TICKET_1f80f5e7bcdad060f7c0de95889541f704979f10?alf_ticket=TICKET_1f80f5e7bcdad060f7c0de95889541f704979f10
Note here that, we have to also explicitly pass alf_ticket querystring parameter as well in order to execute the web script.
If the ticket is valid for the given user, it will return 200 OK as the response. If the ticket is already expired or belongs to some other user then it will return 404 NOT FOUND as the response.
Hope this fast facts will be helpful to you.
How to obtain alf_ticket?
There is an out-of-the-box login web script available in Alfresco wherein you can provide username and password and in return this web script will return you the ticket information for user's established authenctiated session against the alfresco repository. Following are the details about the login web script.
Login web script url - http://localhost:8080/alfresco/service/api/login?u=admin&pw=admin
Login web script response - <ticket>TICKET_1f80f5e7bcdad060f7c0de95889541f704979f10</ticket>By default the webscript returns the XML response, however, you can get the JSON response as well. Just modify the web script URL above with login.json instead of login to get the JSON response back.
For login web script, both GET and POST methods are supported. Ideally, it is preferable to invoke login web script with POST method.
How to use the alf_ticket?
Once you have obtained the alf_ticket for a user then while invoking any further web scripts (which have authentication attribute setup as user in the web script description document), you need to pass the alf_ticket information in order to let the Alfresco repository know that it needs to execute the requested web script code in the context of a user whose authentication ticket information has been passed using alf_ticket.
Following is one example about how you pass alf_ticket to execute the get content web script run in the context for the admin user's authentication session for which we just obtained alf_ticket above.
http://localhost:8080/alfresco/service/api/node/content/workspace/SpacesStore/18d2fa04-70ba-4865-afe6-e097b75f0576?alf_ticket=TICKET_1f80f5e7bcdad060f7c0de95889541f704979f10
If web script itself is expecting some other querystring parameters then you can append alf_ticket at the end using &alf_ticket.
Does the alf_ticket expire?
By default, it is pre-configured in Alfresco that authentication tickets do get expired. The following configuratoin property takes care of setting up whether authentication tickets will expire or not. You can set this property to false in alfresco-global.properties file, if you do not want the alf_ticket to get expired. However, you may not want to do that in regular scenarios.
authentication.ticket.ticketsExpire=true
What is the expiry mode for alf_ticket?
If ticket expiry mode is set as true as mentioned in above configuration property then you can also configure when should alf_ticket get expired. The following configuration property takes care of it.
authentication.ticket.expiryMode=AFTER_INACTIVITY
By default, it is set to AFTER_INACTIVITY (we will see in next section how does it is determined that user is inactive). You can configure this property's value in alfresco-global.preoprties file.
The other two possible values for this configuration property are AFTER_FIXED_TIME and DO_NOT_EXPIRE.
When authentication.ticket.ticketsExpire is set to true, you should either set this property to AFTER_INACTIVITY or AFTER_FIXED_TIME. When authentication.ticket.ticketsExpire is set to false then use DO_NOT_EXPIRE as the value.
When does alf_ticket expire?
When authentication.ticket.ticketsExpire is set as true and authentication.ticket.expiryMode is set as AFTER_INACTIVITY or AFTER_FIXED_TIME then you can configure what is the valid duration for alf_ticket validity using the following property authentication.ticket.validDuration in alfresco-global.properties file.
By default, it is configured to be valid for PT1H i.e. valid for one hour.
The way it works is, if expiryMode is set as AFTER_INACTIVITY then if user does not do any activity during one hour then ticket automatically gets expired.
If expiryMode is set as AFTER_FIXED_TIME then if user do or don't do any activity then still the ticket gets expired after one hour.
How to invalidate alf_ticket explicitly?
For example, when user logs out you may want to invalidate the user ticket at the same time as soon as user is logged out. In order to do so, you can use out-of-the-box Alfresco web script.
Web script URL http://localhost:8080/alfresco/service/api/login/ticket/TICKET_1f80f5e7bcdad060f7c0de95889541f704979f10?alf_ticket=TICKET_1f80f5e7bcdad060f7c0de95889541f704979f10.
It uses the HTTP method DELETE. Also, note that we also have explicitly provided alf_ticket querystring parameter as well.
How to validate if alf_ticket is still valid or not?
If at any point of time, you want to find out if alf_ticket for the user is still valid or not, you can use the following out-of-the-box Alfresco web script. It is basically the same web script url we used in above section however, it is invoked using HTTP GET method instead of DELETE.
http://localhost:8080/alfresco/service/api/login/ticket/TICKET_1f80f5e7bcdad060f7c0de95889541f704979f10?alf_ticket=TICKET_1f80f5e7bcdad060f7c0de95889541f704979f10
Note here that, we have to also explicitly pass alf_ticket querystring parameter as well in order to execute the web script.
If the ticket is valid for the given user, it will return 200 OK as the response. If the ticket is already expired or belongs to some other user then it will return 404 NOT FOUND as the response.
Hope this fast facts will be helpful to you.
