Welcome to Obsidian’s documentation!¶
Obsidian is an OAuth-based Authentication System.It also supports Resource Owner Password Credentials so you can use it as a normal CAS System.
Getting Started¶
Installation Guide on Linux¶
This document is a guide for installation Obsidian on a Linux Distribution. For installation on Windows, see Installation Guide on Windows
Obtain Compiled Obsidian Files¶
Compile by configuration bash script¶
You need to compile Obsidian on your own because we have not provided compiled files. A bash script has been provided for configuring compiling environment.
You can configure compiling environment by the following command if in Ubuntu:
curl -o- https://raw.githubusercontent.com/ZA-PT/Obsidian/canary/configure_env/ubuntu/configure_env.sh | bash
After configuration, you can build and publish Obsidian:
./build.sh | dotnet publish
All runnable files can be found in /home/Obsidian/src/Debug/netcoreapp2.0/publish
Remember to obtain root permissions before you run.
Run Obsidian¶
Change your working directory of your shell to published Obsidian files, /home/Obsidian/src/Debug/netcoreapp2.0/publish in default. Run Obsidian by the following command:
dotnet Obsidian.dll
Obsidian will host itself and listen on port 5000 in default. You can visit http://localhost:5000/ to access Obsidian.
Configure Reverse Proxy Server¶
You need to configure a reverse proxy server if you want to host more websites on your server and access through port 80. A reverse proxy server is able to transfer HTTP requests between Web Server and Obsidian.
In this sector, we use Nginx as web server and configure a reverse proxy server on it.
Install Nginx, add a new vhost with the following configuration:
server {
listen 80;
server_name yourdomain;
location / {
proxy_pass http://localhost:5000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection keep-alive;
proxy_set_header Host $http_host;
proxy_cache_bypass $http_upgrade;
}
}
save and restart Nginx, now you can visit Obsidian through yourdomain.
Install Obsidian as Service¶
In order to make Obsidian start automatically, Obsidian must be installed as service or run by other monitoring software. In this sector, we use Supervisor as monitoring software, which can monitor Obsidian and restart it automatically.
Install Supervisor, add a new program with the following configuration:
[program:obsidian]
directory = /home/Obsidian/src/Debug/netcoreapp2.0/publish
command = dotnet Obsidian.dll
autostart = true
startsecs = 5
autorestart = true
startretries = 3
user = www
redirect_stderr = true
stdout_logfile_maxbytes = 20MB
stdout_logfile_backups = 20
stdout_logfile = /data/logs/Obsidian_stdout.log
Please make sure that every part of path exists, or it can not run correctly. Save this configuration files in Supervisor Configuration Directory.
Finally, refresh Supervisor:
supervisorctl update
Obsidian will automatically run now.
Install MongoDB¶
Obsidian stores its datas in MongoDB so you need to install Mongodb. If your MongoDB listen at default port, Obsidian will work correctly.
If you want to set a custom MongoDB connection string, edit appsettings.json in Obsidian working directory, /home/Obsidian/src/Debug/netcoreapp2.0/publish/appsettings.json default:
{
"ApplicationInsights": {
"InstrumentationKey": ""
},
"Logging": {
"IncludeScopes": false,
"LogLevel": {
"Default": "Debug",
"System": "Information",
"Microsoft": "Information"
}
},
"OAuth20": {
"TokenAudience": "ObsidianAud",
"TokenIssuer": "Obsidian"
},
"ConnectionStrings": {
"MongoDB": "mongodb://127.0.0.1:27017"
}
}
replace “MongoDB” sector will correct connection string.
Configure Obsidian¶
Now visit http://yourdomain/firstrun to setup Obsidian. You need to provide administrator’s username, password and Obsidian URL.
Please make sure that Obsidian has permissions creating files in its working directory because The FirstRun program will create init.txt after setting up.
Finally, Obsidian will redirect you to Management Portal, where you can create scope,user or client.
Eventually, you have your Obsidian installed.
Installation Guide on Windows¶
Claims in Obsidian OAuth Server¶
Claims in OAuth Server¶
Though Obsidian is mainly designed as an OAuth Authentication Server, the whole Obsidian program is commonly divided into three parts. On one hand, Obsidian’s user model contains user’s personal information which will be provided to third-part client on OAuth process, on the other hand, because it contains user’s information, it can be regarded as a Resource Server.
Claims in user domain model mainly represent user’s personal information instead of what a user can do.
Claims list¶
| Model | ClaimType | Content |
|---|---|---|
| User | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier | User Id of user model |
| User | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name | Username of user model |
| UserProfile | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname | User’s givenname |
| UserProfile | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname | User’s surname |
| UserProfile | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender | User’s gender |
| UserProfile | http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress | User’s email emailaddress |
Claims in Obsidian Management API¶
Introduce¶
Obsidian uses Token-based Authentication and Claims-based Authorization.
If user wants to access a manament API action, a JsonWebToken must be added into the request.JsonWebToken generated by Obsidian OAuth Server contains claims that user owns. Some claims represent user’s personal information, others represent permissions which user is endowed with.
Strictly speaking, A claim can not represent what a user can/can not do. However, if we want a user to be able to edit something, we can give it a claim that tells other it is an editor instead of a claim that contains what resource it can operate
In this section, we mainly list all available claims that can be given to user.
For claims represented user’s personal information, see Claims in Obsidian OAuth Server
Claims list¶
Contribution Guide¶
Obsidian is an open source software. You can re-develop Obsidian within the limits permitted by Apache 2.0 License.
This chapter is to give someone who wants to participate in development of Obsidian.
Toolkit Installation¶
- Make sure these following tools are installed:
- .NET Core 1.1.1 with SDK 1.0.1
- Yarn Package Manager
2. Run the following commands:
cd ./src/Obsidian/
dotnet restore
dotnet --verbose build
yarn
Name Convention¶
For C# code¶
References
using System;
using System.Threading.Tasks;
//For namespaces, use Pascal casing.
namespace NamingConversions
{
// For classes, enums, use Pascal casing.
public class SampleClass
{
//For constanrs, use Pascal casing.
public const int Count = 0;
//For static menbers, use Pascal casing.
//For public fields, use Pascak casing.
public static string Name = "Obsidian";
//For private fieldss, use camel case with an unserscore.
private string _name;
//For properties, use Pascal casing.
public string StatusData { get; set; }
//For methods, use Pascal casing.
//For parameters, use camel casing.
public void MyMethod(int myParameter)
{
}
//For asynchronous methods, use Pascal casing with subfix "Async".
public async Task ProcessAsync()
{
}
//For events, use Pascal casing.
public event EventHandler MyEvent;
}
//For interfaces, use Pascal casing with prefix "I".
public interface ISample
{
}
}