As part of the security best practices, a lot of admins in Office 365 setup their user password policy in a way that the password needs to be changed every 3 months. Though this is very good for end user account security, it can pose challenge for service accounts being used in the applications to make REST or CSOM calls to SharePoint Online as these external apps can be broken if password for service account is changed in Office 365 but is not modified on the application side. This is specially subject to the admin unknowingly changing the password for service account without realizing it has been used in the application.
Access tokens in an AgilePoint NX application can run into same scenario if service account which is used in access token has a password which gets modified every 3 months and it has been configured for claims based authentication which utilizes the password.
This is where OAuth2 authentication comes to the rescue. Instead of authenticating using service account using password, you can use app based authentication which is OAuth2 based. This way your service account password can change every 3 months without you being effected by the change.
Please follow the following steps to generate client id and secret to create access tokens in AgilePoint NX. I have explained here using a dummy app however if users have some existing apps which have desired permissions, they can use the client id and secret from that app.
Please note that Microsoft App’s client secret created using AppRegNew.aspx page, expires every 1 year as well. Therefore, you will still have to replace this every year but you still get an advantage that all calls are independent of user/service account and not subject to someone changing password unknowingly. The fact that it expires every year is covered in the following article from Microsoft.
If you wish to create client secret with longer expiration time, it can be done using PowerShell which is covered after the UI option.
Also note that, for any new Office 365 tenants spinned up after November 7, 2018, apps using an ACS app-only access token is disabled by default. If you have a newer tenant, you can change the behavior by running following command using the latest SharePoint admin PowerShell).
Connect-SPOService -Url https://<your O365 tenant name>-admin.sharepoint.com/
Set-SPOTenant -DisableCustomAppAuthentication $false
If this step is not performed, you would get the following error when you try to validate the access token.
“The remote server returned an error: (401) Unauthorized.”
UI Option:
Step 1: Register dummy app in O365 : Navigate to the SharePoint Office365 page <<SharePoint site url>>/_layouts/15/appregnew.aspx for ex : https://agilepoint462.sharepoint.com/Sites/qa/_layouts/15/appregnew.aspx
On appregnew page you can generate new client secret and client id by clicking on generate button and then provide some dummy data in rest of the fields as shown below and then click on create button. After it is created you can use this client secret and client id to create access token in AgilePoint.
Client Id: XXXXXX
Client Secret: XXXXXX
Title: AgilePoint
App Domain: www.agilepoint.com
Redirect URI: https://www.agilepoint.com
Note: Please save your client id and secret in a permanent location as you won’t be able to retrieve it later.
Step 2: Assign Permission to the dummy app: Navigate to the SharePoint Office365 page <<SharePoint site url>>/_layouts/15/appinv.aspx for ex : https://agilepoint462.sharepoint.com/Sites/qa/_layouts/15/appinv.aspx and in app id field provide the above create client id and click lookup button, it will display your app’s information on the page. In the Permission Request XML field just paste the below xml and click save.
<AppPermissionRequests AllowAppOnlyPolicy=”true”>
<AppPermissionRequest Scope=”http://sharepoint/content/sitecollection/web” Right=”FullControl” />
<AppPermissionRequest Scope=”http://sharepoint/content/sitecollection” Right=”FullControl” />
</AppPermissionRequests>
Note: Please copy this text into a notepad first and replace all double quotes with proper format before copying that over to SharePoint page. WordPress messes up the double quote format which if pasted directly in the SharePoint page will throw an error. Please note that no other changes are required and the URLs should be used as shown above else permissions won’t be set correctly.
On the next page click on Trust it button and your dummy app will be registered and permissions are assigned and it is ready to use.
Step 3: Go to AgilePoint Portal -> Manage and create a SharePoint access token. Provide your Office 365 site collection URL and select Oauth2 Authentication -> Office 365 and provide your client id and secret and click on test connection button to see if the authentication succeeds.
PowerShell Option:
Using this option, you can create client secret with longer expiration time.
Step 1: Download and Install SharePoint Online Management Shell from this link : https://www.microsoft.com/en-in/download/details.aspx?id=35588
Step 2: Open SharePoint Online Management Shell as Administrator.
Step 3: Run below command in SharePoint Online Management Shell and it will prompt for credentials, enter the valid credentials to connect to SharePoint Online (Use an account which has permissions to register an App, usually this is done using Global Administrator account). Please note that you need to replace at sign where mentioned as text editor considers that a sepcial character.
# Command to create an app using PowerShell
$clientID=”d0ab675c-30b1-41f8-babb-33982d643c4e”; # Create a new GUID and provide here
$bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
$appDomain=”Yourdomain.azurewebsites.net”; # Provide your app domain name
$appUrl=”https://Yourdomain.azurewebsites.net“; # Provide your app domain url
$appName=”AgilePoint Access Token App” # Provide a name for your app
$servicePrincipalName = <replace with at sign>(“$clientID/$appDomain”)
$dtStart = [System.DateTime]::Now
$dtEnd = $dtStart.AddYears(10) # Set the expiration time in years for your app, for this example I have added 10 years
Connect-MsolService
New-MsolServicePrincipal -ServicePrincipalNames $servicePrincipalName -AppPrincipalId $clientID -DisplayName $appName -Type Symmetric -Usage Verify -Value $newClientSecret -Addresses (New-MsolServicePrincipalAddresses -Address $appUrl) -StartDate $dtStart –EndDate $dtEnd
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Symmetric -Usage Sign -Value $newClientSecret -StartDate $dtStart –EndDate $dtEnd
New-MsolServicePrincipalCredential -AppPrincipalId $clientId -Type Password -Usage Verify -Value $newClientSecret -StartDate $dtStart –EndDate $dtEnd
Step 4: After the command is ran successfully it will show information in the command window which includes Client ID.
Step 5: Retrieve new created Client Secret using below command
write-host $newClientSecret
Step 6: Copy Client ID, Client Secret, DisplayName, ServicePrincipalNames, StartDate and EndDate for later purposes.
Step 7: Assign Permission to the app: Navigate to the SharePoint Office365 page <<SharePoint site url>>/_layouts/15/appinv.aspx for ex : https://agilepoint462.sharepoint.com/Sites/qa/_layouts/15/appinv.aspx and in app id field provide the above create client id and click lookup button, it will display your app’s information on the page. In the Permission Request XML field just paste the below xml and click save.
<AppPermissionRequests AllowAppOnlyPolicy=”true”>
<AppPermissionRequest Scope=”http://sharepoint/content/sitecollection/web” Right=”FullControl” />
<AppPermissionRequest Scope=”http://sharepoint/content/sitecollection” Right=”FullControl” />
</AppPermissionRequests>
Note: Please copy this text into a notepad first and replace all double quotes with proper format before copying that over to SharePoint page. WordPress messes up the double quote format which if pasted directly in the SharePoint page will throw an error. Please note that no other changes are required and the URLs should be used as shown above else permissions won’t be set correctly.
On the next page click on Trust it button and your dummy app will be registered and permissions are assigned and it is ready to use.
Step 8: Go to AgilePoint Portal -> Manage and create a SharePoint access token. Provide your Office 365 site collection URL and select OAuth2 Authentication -> Office 365 and provide your client id and secret and click on test connection button to see if the authentication succeeds.
Lastly, if the client secret got expired, you can follow the steps mentioned below to reset the client secret.